pikvm/docs/building_os.md

Building PiKVM OS

The assembly of PiKVM OS is carried out using a special build environment. Here the minimum required for its use, imposed on the build machine:

• kernel >= 5.8
• glibc >= 2.33
• docker >= 19.03.13
• git

Docker must work in privileged mode.

1. When starting with a clean OS you need to install and configure Docker. An example for Ubuntu:

   [user@localhost ~]$ sudo apt-get install git make curl binutils -y
   [user@localhost ~]$ sudo apt-get install docker.io
   [user@localhost ~]$ sudo usermod -aG docker $USER
   

   Re-login to apply the changes.

2. Checkout the build environment:

   [user@localhost ~]$ git clone --depth=1 https://github.com/pikvm/os
   [user@localhost ~]$ cd os
   

3. Determine the target board and platform:

   • Choose the board:

     • BOARD=rpi4 for Raspberry Pi 4.
     • BOARD=zero2w
     • BOARD=rpi3
     • BOARD=rpi2

   • Choose the platform:

     • PLATFORM=v4mini-hdmi for PiKVM V4 Mini.
     • PLATFORM=v4plus-hdmi for PiKVM V4 Plus.
     • PLATFORM=v3-hdmi for RPi4 and PiKVM V3 HAT.
     • PLATFORM=v2-hdmi for RPi3a+/RPi4 or Zero2W with HDMI-CSI bridge.
     • PLATFORM=v2-hdmiusb for RPi4 with HDMI-USB dongle.
     • PLATFORM=v1-hdmi for RPi2 or 3b+ with HDMI-CSI bridge and the Pico HID.
     • PLATFORM=v1-hdmiusb for RPi2 or 3b+ with HDMI-USB dongle and the Pico HID.

4. Create the build config file config.mk for the target system and and the BOARD and PLATFORM variables. You can also set some other parameters as you wish (see below). Please note: if your password contains the # character, you must escape it using a backslash like ROOT_PASSWD = pass\#word.

   # Base board
   BOARD = rpi4
   
   # Hardware configuration
   PLATFORM = v2-hdmi
   
   # Target hostname
   HOSTNAME = pikvm
   
   # ru_RU, etc. UTF-8 only
   LOCALE = en_US
   
   # See /usr/share/zoneinfo
   TIMEZONE = Europe/Nicosia
   
   # For SSH root user
   ROOT_PASSWD = rootpass
   
   # Web UI credentials: user=admin, password=adminpass
   WEBUI_ADMIN_PASSWD = adminpass
   
   # IPMI credentials: user=admin, password=adminpass
   IPMI_ADMIN_PASSWD = adminpass
   

5. Build the OS. It may take about one hour depending on the Internet connection:

   [user@localhost os]$ make os
   

   !!! tip If you get an error about failing to retrieving a file, please edit the Makefile and remove de3. from the repo URL.

6. Create an image. It will be stored in the images directory as a file with *.img extension:

   [user@localhost os]$ make image
   

7. Flash the result image to SD card.