start-os/BuildGuide.md

Initial Notes & Recommendations

• Due to issues to cross-compile the image from a desktop, this guide will take you step-by-step through the process of compiling EmbassyOS directly on a Raspberry Pi 4 (4GB or 8GB)
• This process will go faster if you have an SSD/NVMe USB drive available.
• This build guide does not require a large microSD card, especially if your final build wil be used on an SSD/NVMe USB drive.
• Basic know-how of linux commands and terminal use is recommended.
• Follow the guide carefully and do not skip any steps.

🛠️ Build Guide

1. Flash Raspberry Pi OS Lite to a microSD and configure your raspi to boot from SSD/NVMe USB drive

   1. After flashing, create an empty text file called ssh in the boot partition of the microSD, then proceed with booting the raspi with the flashed microSD (check your router for the IP assigned to your raspi)
   2. Do the usual initial update/config

      sudo apt update
      sudo raspi-config
      

   3. Change Advanced Options->Boot Order
   4. Select USB Boot (it will try to boot from microSD first if it's available)
   5. Select Finish, then Yes to reboot
   6. After reboot, sudo shutdown now to power off the raspi and remove the microSD

2. Flash the Raspi OS Lite (from step 1) to your SSD/NVMe drive

   ℹ️ Don't worry about rootfs partition size (raspi will increase it for you on initial boot)

   ℹ️ Every time you re-flash your SSD/NVMe you need to first boot with a microSD and set Boot Order again

   1. Don't forget to create the empty ssh file
   2. Connect the drive (remember to remove the microSD) to the raspi and start it up
   3. Use sudo raspi-config to change the default password
   4. Optional: sudo apt upgrade -y
   5. Optional: sudo nano /etc/apt/sources.list.d/vscode.list comment the last line which contains packages.microsoft.com

3. Install GHC

   sudo apt update
   sudo apt install -y ghc
   
   #test:
   ghc --version
   
   #example of output:
   The Glorious Glasgow Haskell Compilation System, version 8.4.4
   

4. Compile Stack:

   1. Install Stack v2.1.3

      cd ~/
      wget -qO- https://raw.githubusercontent.com/commercialhaskell/stack/v2.1.3/etc/scripts/get-stack.sh | sh
      
      #test with
      stack --version
      
      #example output:
      Version 2.1.3, Git revision 636e3a759d51127df2b62f90772def126cdf6d1f (7735 commits) arm hpack-0.31.2
      

   2. Use current Stack to compile Stack v2.5.1:

      git clone --depth 1 --branch v2.5.1 https://github.com/commercialhaskell/stack.git
      cd stack
      sudo apt install -y screen
      screen
      

      ℹ️ Build (>=3.5h total... We are using screen in case of session timeout issues)

      📝 If you get disconected you can reattach last sesion again by executing screen -r

      stack build --stack-yaml=stack-ghc-84.yaml --system-ghc
      
      #Install
      stack install --stack-yaml=stack-ghc-84.yaml --system-ghc
      export PATH=~/.local/bin:$PATH
      

5. Clone EmbassyOS & try to make the agent:

   1. First attempt

      ℹ️ The first time you run make you'll get an error

      sudo apt install -y llvm-9 libgmp-dev
      export PATH=/usr/lib/llvm-9/bin:$PATH
      cd ~/
      git clone https://github.com/Start9Labs/embassy-os.git
      cd embassy-os/
      make agent
      

      📝 This will install ghc-8.10.2, then attempt to build but will give errors (in next steps we deal with errors)

   2. Confirm your cpu info

      cat /proc/cpuinfo | grep Hardware
      

   3. If your "Hardware" is BCM2711 then:

      1. Change C compiler flags to -marm -fno-stack-protector -mcpu=cortex-a7 in the GHC settings:

         nano ~/.stack/programs/arm-linux/ghc-8.10.4/lib/ghc-8.10.4/settings
         

   4. To prevent gcc errors we delete the setup-exe-src folder

      rm -rf ~/.stack/setup-exe-src/
      

6. Install requirements for step 7

   1. Install NVM

      cd ~/ && curl -o- https://raw.githubusercontent.com/nvm-sh/nvm/v0.35.3/install.sh | bash
      export NVM_DIR="$HOME/.nvm"
      [ -s "$NVM_DIR/nvm.sh" ] && \. "$NVM_DIR/nvm.sh"  # This loads nvm
      [ -s "$NVM_DIR/bash_completion" ] && \. "$NVM_DIR/bash_completion"  # This loads nvm bash_completion
      nvm --version
      

   2. Install Node.js & NPM

      nvm install node
      

   3. Install Ionic CLI

      npm install -g @ionic/cli
      

   4. Install Dependencies

      sudo apt-get install -y build-essential openssl libssl-dev libc6-dev clang libclang-dev libavahi-client-dev upx ca-certificates
      

   5. Install Rust

      cd ~/ && curl --proto '=https' --tlsv1.2 -sSf https://sh.rustup.rs -o- | bash
      
      #Choose option 1
      source $HOME/.cargo/env
      
      #Check rust & cargo versions
      rustc --version
      cargo --version
      

7. Finally, getting to build the .img

   1. At this stage you hava a working development environment to build your embassy.img. Before you do that you can choose to enable SSH login for user pi in case something will go wrong or just skip to the next step.

      cd ~/embassy-os
      sed -e '/passwd -l pi/ s/^#*/#/' -i setup.sh
      

      ⚠️ Default password for user pi is raspberry, change it the next you login.

   2. Build the embassy.img

      cd ~/embassy-os
      make
      
      #Depending on your hardware this can take 1-2h+
      #Wait for the "DONE!" message and take note of your product_key
      exit
      

8. Flash the embassy.img to a microSD

   1. Copy embassy.img from the raspi to your PC with scp

      scp pi@raspi_IP:~/embassy-os/embassy.img .
      

   2. Connect to raspi again to do sudo shutdown now, after a complete shutdown disconnect SSD/NVMe drive
   3. Flash embassy.img to a microSD (do this before flashing to the SSD/NVMe, to be sure it works)

9. Prepare for initial setup

   1. Boot raspi using flashed microSD
   2. After a few minutes, the raspi should reboot itself and make it's first sounds.

      ℹ️ If needed, you can check the agent log with: journalctl -u agent -ef

   3. Proceed with the initial setup process of EmbassyOS
   4. If all went well you can safely flash embassy.img to an SSD/NVMe and repeat step 9

Embassy sounds explained

Sound 🎶	Indicating
Bep	Device is powering on
Chime	Device is ready for setup
Mario "Coin"	EmbassyOS has started
Mario "Death"	Device is about to Shutdown/Reboot
Mario "Power Up"	EmbassyOS update sequence
Beethoven	Update failed :(