Compiling EmbassyOS v0.3 in Ubuntu

This guide will cover how to compile EmbassyOS v0.3 using a fresh install of Ubuntu.

Currently the only supported hardware for EmbassyOS is the Raspberry Pi 4b — though that will not be the case for much longer as we bring out the Embassy Pro — this will run on a Purism Librem Mini (an x86 Intel Nuc). This guide will not be covering how to compile for that though — just the Raspberry Pi.

If you are migrating from version v0.2, you will need a 16gb micro SD card (make sure it’s actually 16gb — sometimes they are only 15.6gb), a reader for the micro SD card and an SSD + USB adapter/enclosure for it.

A complete list of the equipment needed to migrate from 0.2.x can be found here.

If you initially bought 0.2.x from us, there is no need to compile v0.3 — you can simply head here, enter your product key and download an image.

If you are making an Embassy from scratch you will need the equipment listed here.

Everything is explained in that guide, except for how to compile the actual OS which I’ll go over in this article.

Now onto building the image.

We’ll start in a fresh install of Ubuntu.

Brand new Ubuntu 20.04.2

Click in the bottom left on the 9 dots, type “terminal” then hit enter.

Now enter sudo apt update

Followed by sudo apt upgrade -y

Once it has finished upgrading we’ll install git by typing sudo apt install git

Installing Git

Hit y when it asks if you want to continue.

Next we’ll need Docker.

sudo apt install docker.io -y

Installing Docker

Now add your user sudo usermod -a -G docker $USER

Adding your $USER

Then run newgrp docker

newgrp docker

Now for buildx:

wget https://github.com/docker/buildx/releases/download/v0.6.3/buildx-v0.6.3.linux-amd64

Then run these six commands:

chmod a+x buildx-v0.6.3.linux-amd64
mkdir -p ~/.docker/cli-plugins 
mv buildx-v0.6.3.linux-amd64 ~/.docker/cli-plugins/docker-buildx
docker run --privileged --rm linuxkit/binfmt:v0.8
docker buildx create --use
sudo systemctl start docker

That’s Docker done.

Next dependency: NodeJS

Grab it by running these two commands:

wget https://nodejs.org/dist/v16.13.0/node-v16.13.0-linux-x64.tar.xz
tar -xvf node-v16.13.0-linux-x64.tar.xz

Now add it to your path:

echo "export PATH=$PATH:~/node-v16.13.0-linux-x64/bin" >> ~/.bashrc
source ~/.bashrc

Add node to your path

Next dependency — Rust:

sudo apt-get install curl -y
curl https://sh.rustup.rs -sSf | sh

Install Rust

It will ask you to select an option. Choose option 1.

Hit 1 and press enter

Now add Rust to your path:

echo "export PATH=/home/parallels/.cargo/bin:$PATH" >> ~/.bashrc
source ~/.bashrc

Next dependency — JQ:

sudo apt install jq -y

Then finally, Avahi:

sudo snap install avahi

Now we can clone the Embassy-OS directory from GitHub:

git clone https://github.com/start9labs/embassy-os

Change into the embassy-os directory:

cd embassy-os

At this time of writing, the commit to checkout is 5d3bc8cfa5b6f283045cdb3ebf3c79c7bbe6fb4d

Do this by typing in:

git checkout 5d3bc8cfa5b6f283045cdb3ebf3c79c7bbe6fb4d

But please note — in the future you will want to checkout something much more recent. Master should usually and can be simply checked out like this:

git checkout master

Once on the correct commit, git stash and finally:

git submodule update --init --recursive

Now we’re on the correct commit with all the dependencies installed. Time to make the image!

#If you are building a brand new Embassy:
make
#If you are migrating from 0.2.x and already have a product key...
make KEY=YOUR_PRODUCT_KEY

Watch as your Embassy image is built from scratch.

You will be asked to enter your password towards the end of this process.

Enter your password (you won’t see your typing)

Now once your image has been built, you will see this:

Here you can type ls and in the directory, you will see eos.img and product_key.txt

Type `ls`

Type in cat product_key.txt to learn your product key as you will need this for the setup wizard.

Now to finish setting up your Embassy, please follow the DIY guide linked at the start of this article which will tell you to flash the image you just created onto the 16gb SD card, put it in the Raspberry Pi, attach the SSD and the Ethernet cable and finally attach the power.

After ~35 minutes you should hear a short ‘bep’ and then a chime.

Once you’ve heard those sounds, head to http://embassy.local on any machine on the same LAN as your Embassy and go through setup.

If you run into any issues with this guide or have any suggestions, please head to our Matrix server.

Enjoy your Embassy!

~Mechanic

If this guide helped you and you’d like to support the project, you can donate here:

bc1qdah5dculyuw8c6f3wzzannpjt4w5and4knf87h