start-os/build

Building StartOS

⚠️ 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: nvm install --lts
  • https://nodejs.org/en/docs
• NPM Version 7+
  • apt: sudo apt install -y npm
  • nvm: 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

   ℹ️ You chan check latest available version here

   git clone --recursive https://github.com/Start9Labs/start-os.git --branch latest
   

Build Raspberry Pi Image

cd start-os
make embassyos-raspi.img ARCH=aarch64

Flash

Flash the resulting embassyos-raspi.img to your SD Card

We recommend Balena Etcher

Setup

Visit http://start.local from any web browser - We recommend Firefox

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 StartOS, bootup sounds and all, but my browser is saying "Unable to connect" with start.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 StartOS 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?

• Find the IP of your device
• Run nc <ip> 8080 and it will print the logs

4. I need to ssh into my server to fix something, but I cannot get to the console to add ssh keys normally.

• During the Build step, instead of running just make embassyos-raspi.img ARCH=aarch64 run ENVIRONMENT=dev make embassyos-raspi.img ARCH=aarch64. Flash like normal, and insert into your server. Boot up StartOS, then on another computer on the same network, ssh into the the server with the username start9 password embassy.

4. I need to reset my password, how can I do that?

• You will need to reflash your device. Select "Use Existing Drive" once you are in setup, and it will prompt you to set a new password.