# Building Embassy OS

 ⚠️ The commands given assume a Debian or Ubuntu-based environment.  *Building in a VM is NOT yet supported* ⚠️

## Prerequisites

1. Install dependencies

- Avahi
	- `sudo apt install -y avahi-daemon`
	- Installed by default on most Debian systems - https://avahi.org
- Build Essentials (needed to run `make`)
	- `sudo apt install -y build-essential`
- Docker
	- `curl -fsSL https://get.docker.com | sh`
	- https://docs.docker.com/get-docker
	- Add your user to the docker group: `sudo usermod -a -G docker $USER`
	- Reload user environment `exec sudo su -l $USER`
- Prepare Docker environment
	- Setup buildx (https://docs.docker.com/buildx/working-with-buildx/)
	- Create a builder: `docker buildx create --use`
	- Add multi-arch build ability: `docker run --rm --privileged linuxkit/binfmt:v0.8`
- Node Version 12+
	- snap: `sudo snap install node`
	- [nvm](https://github.com/nvm-sh/nvm#installing-and-updating): `nvm install --lts`
	- https://nodejs.org/en/docs
- NPM Version 7+
	- apt: `sudo apt install -y npm`
	- [nvm](https://github.com/nvm-sh/nvm#installing-and-updating): `nvm install --lts`
	- https://docs.npmjs.com/downloading-and-installing-node-js-and-npm
- jq
	- `sudo apt install -y jq`
	- https://stedolan.github.io/jq
- yq
	- snap: `sudo snap install yq`
	- binaries: https://github.com/mikefarah/yq/releases/
	- https://mikefarah.gitbook.io/yq

2. Clone the latest repo with required submodules
   > :information_source: You chan check latest available version [here](https://github.com/Start9Labs/embassy-os/releases)
	```
	git clone --recursive https://github.com/Start9Labs/embassy-os.git --branch latest
	```

## Build

```
cd embassy-os
make
```

## Flash

Flash the resulting `eos.img` to your SD Card (16GB required, any larger is neither necessary, nor advantageous)

We recommend [Balena Etcher](https://www.balena.io/etcher/)

## Setup

Visit http://embassy.local from any web browser - We recommend [Firefox](https://www.mozilla.org/firefox/browsers)

Enter your product key. This is generated during the build process and can be found in `product_key.txt`, located in the root directory.

## Troubleshooting

1. I just flashed my SD card, fired up my Embassy, bootup sounds and all, but my browser is saying "Unable to connect" with embassy.local.

- Try doing a hard refresh on your browser, or opening the url in a private/incognito window. If you've ran an instance 
  of Embassy before, sometimes you can have a stale cache that will block you from navigating to the page.

2. Flashing the image isn't working with balenaEtcher. I'm getting `Cannot read property 'message' of null` when I try.
- The latest versions of Balena may not flash properly. This version here: https://github.com/balena-io/etcher/releases/tag/v1.5.122 should work properly.

3. Startup isn't working properly and I'm curious as to why. How can I view logs regarding startup for debugging? 
- During the Build step, instead of running just `make` run `ENVIRONMENT=dev make`. Flash like normal, and insert into your Embassy. Boot up your Embassy, and on another computer
on the same network, ssh into the Embassy with the username/password `ubuntu`.  After logging in and changing the password, run `journalctl -u initialization.service -ef` to view the start up logs.

4. I need to reset my password, how can I do that?
- At the time of writing, there is no way to do that in 0.3.0 cleanly. You'll need to reflash your device unfortunately.