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.
Click in the bottom left on the 9 dots, type “terminal” then hit enter.
sudo apt update
sudo apt upgrade -y
Once it has finished upgrading we’ll install git by typing
sudo apt install git
y when it asks if you want to continue.
Next we’ll need Docker.
sudo apt install docker.io -y
Now add your user
sudo usermod -a -G docker $USER
Now for buildx:
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:
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
Next dependency — Rust:
sudo apt-get install curl -y
curl https://sh.rustup.rs -sSf | sh
It will ask you to select an option. Choose option 1.
Now add Rust to your path:
echo "export PATH=/home/parallels/.cargo/bin:$PATH" >> ~/.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:
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.
Now once your image has been built, you will see this:
Here you can type
ls and in the directory, you will see
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!
If this guide helped you and you’d like to support the project, you can donate here: