Installation

These instructions constitute manual installation instructions. They exist here as documentation, but as we approach fully automatic provisioning, operators should not require to do any of these manual steps.

An example of this is in our Excalidraw here:

And here: https://link.excalidraw.com/l/AQPpvHjLpqe/3LQpJd8mWeX

The below instructions are intended only for single disk platforms. More complex disk platforms should follow up on Storage Configuration.

1. On your local device, clone nixpkgs-matrix-private

# If you are using SSH authentication
git clone git@github.com:MatrixAI/nixpkgs-matrix-private.git

# If you are using basic authentication
git clone https://github.com/MatrixAI/nixpkgs-matrix-private.git

cd nixpkgs-matrix-private

2. Build the installation ISO using Nix

nix build .#install

3. Grab a USB (minimum 8GB), plug it into your device, and flash the image

# Find the appropriate drive to flash to (we are assuming here /dev/sdb)
lsblk

# Use dd to flash the drive
sudo dd if=result/nixos/* of=/dev/sdb bs=4M oflag=direct conv=fsync status=progress

4. Unplug the drive and plug it into your target device. You can eject it with eject /dev/sda.
5. In the BIOS settings:

• Disable hardware RAID because we will be using ZFS which performs software RAID.
• Disable secure boot, because we cannot use it with our custom NixOS images.

6. Boot into the installation media, setup the internet with ethernet or WiFi. wpa_supplicant -B -i <wifi-interface> -c <(wpa_passphrase '<ssid>' '<password>')
7. The SSH server should already be running on the installation system, however it can also be started with systemctl start sshd. You do need to setup a password with passwd first.
8. Set up a PAT which will be used to authenticate with GitHub. Create a fine-grained token that has only read-only permissions to the nixpkgs-matrix-private repository. You may need to change it to Matrix AI owner. The PAT must have read permission for the Contents repository permission. See: https://docs.github.com/en/authentication/keeping-your-account-and-data-secure/managing-your-personal-access-tokens
9. Run the matrix-install script which will set up the device

# Arguments for the script
sudo matrix-install <pat> <profile> <disk>

# Find the disk from /dev/disk/by-path
ls -la /dev/disk/by-path

# Lets assume a PAT, profile and disk here
sudo matrix-install ABCD1234 matrix-dell-34xx /dev/disk/by-path/pci-0000:01:00.0-nvme-1

reboot

10. After rebooting, it is time to set up the user account. Log in as root, and run the following to add a user account:

useradd \
  --create-home \
  --no-user-group \
  --gid=operators \
  --groups=wheel,users,networkmanager,docker,adbusers,plugdev,vboxusers,video,audio \
  --comment="$desc" \
  --skel="/etc/skel" \
  "$user"

su - "$user" -c "true"

passwd "$user"

# Copy your public key into .ssh/authorized_keys to be able to ssh in later
# We lock the root account once we have the superuser

passwd --lock root
reboot

11. Should be done!