Libre-Chip server setup scripts

Testing Locally

• This is assuming you're running Debian 13 on your computer, though it will probably work with any non-ancient variant of GNU/Linux. This guide will create a VM with a snapshot so the test-in-vm.sh script can reset it every time for testing installation as many times as you need. But before that, we have to manually prepare the VM first:

• Add the following lines to your host's /etc/hosts:

10.10.10.1 pebble
10.10.10.2 libre-chip.test librechip.test mail.libre-chip.test mail.librechip.test git.libre-chip.test git.librechip.test forum.libre-chip.test forum.librechip.test

• Ensure your local user is in the libvirt group so you can run virsh.
• Ensure the default URI for libvirt is qemu:///system, you can check by running virsh uri. You can change the default by editing /etc/libvirt/libvirt.conf or ~/.config/libvirt/libvirt.conf (which you may need to create first) and uncommenting/adding:

  uri_default = "qemu:///system"
  

• Create a new libvirt network:

  virsh net-define libre-chip-test.xml
  virsh net-autostart libre-chip-test
  virsh net-start libre-chip-test
  

• Get the latest Debian 12 ISO, you can get it from https://cdimage.debian.org/mirror/cdimage/archive/12.15.0/amd64/iso-cd/debian-12.15.0-amd64-netinst.iso
• Using the virt-manager gui frontend, create a new VM with:
  • Local install media (ISO image)
  • Pick the Debian 12 ISO you downloaded above
  • 12GiB (12288 MiB) RAM
  • 6 CPUs
  • A new 30GB disk image
  • The name should be libre-chip.test (this is important)
  • Under "Network selection", choose libre-chip-test (this is important)
  • Click "Finish". The VM should start running.
• In the VM:
  • Go to "Advanced Options" and choose the "Expert install" option.
  • Pick "Choose Language"
    • Pick "English"
    • Choose "United States"
    • Choose "United States - en_US.UTF-8".
    • For additional locales, choose "C.UTF-8".
    • Select "C.UTF-8" as the default locale.
  • Pick "Configure the keyboard".
    • Pick "American English".
  • Pick "Detect and mount installation media".
  • Pick "Load installer components from installation media".
    • Enable "network-console".
  • Pick "Detect network hardware".
  • Pick "Configure the network".
    • For "Auto-configure networking?", pick "No".
    • The IP address should be 10.10.10.2, netmask 255.255.255.0, gateway 10.10.10.1, name server 10.10.10.1.
    • The hostname should be libre-chip, the domain name should be test.
  • Pick "Continue installation remotely using SSH".
    • Use whatever you like as the "Remote installation password".
  • Once you get to the "Start SSH" page, then you can continue on your host with SSH.
• On your host:
  • Start a new terminal
  • Resize the new terminal window to be as big as you like (the installer doesn't deal well with changes in the window size after logging in with ssh)
  • Run ssh installer@libre-chip.test -- this lets you copy and paste things into the terminal instead of having to type everything out.
    • If ssh complains that the host key changed (because you had something else at libre-chip.test before, like a previous version of the VM), run ssh-keygen -R 10.10.10.2 and ssh-keygen -R libre-chip.test to remove the old host, and then run ssh again.
  • Pick the advanced installation option.
  • Pick "Set up users and passwords".
    • For "Allow login as root?", choose "Yes".
    • Choose a suitable root password.
    • For "Create a normal user account now?", choose "No" (this is important).
  • Pick "Configure the clock".
    • For "Set the clock using NTP?", choose "Yes", using the default NTP server.
    • For time zone, choose "Coordinated Universal Time (UTC)".
  • Pick "Detect disks".
  • Pick "Partition disks".
    • For "Partitioning method", choose "Manual".
    • Pick "Virtual disk 1".
      • Create the new empty partition table on that device.
      • For "Partition table type", pick "gpt".
    • Pick "FREE SPACE".
      • Choose "Create a new partition".
      • Choose 1 GB and locate it at the "Beginning".
      • For "Use as", choose "Ext4".
      • For "Mount point", choose "/boot".
      • Select "Done setting up the partition".
    • Pick the lower "FREE SPACE".
      • Choose "Create a new partition".
      • For "New partition size", choose max.
      • For "Use as", choose "btrfs" (this is important).
      • Select "Done setting up the partition".
    • Select "Finish partitioning and write changes to disk".
    • When it complains about no swap space and asks if you want to return to the partitioning menu, choose "No".
    • For "Write the changes to disk?", choose "Yes".
  • Pick "Install the base system".
    • For "Kernel to install", pick "linux-image-amd64" (or whatever one is appropriate for your CPU architecture).
    • For "Drivers to include in the initrd", pick "generic".
    • For "Character set to support", pick "Guess optimal character set".
  • Pick "Configure the package manager".
    • For "Scan extra installation media", choose "No".
    • For "Use a network mirror", choose "Yes".
    • Pick "http".
    • Pick "United States".
    • Pick "deb.debian.org".
    • Leave the proxy blank.
    • Choose "No" for non-free firmware/software and contrib software.
    • Enable source repositories in APT.
    • Leave "security updates", and "release updates" enabled, and "backported software" disabled.
  • Pick "Select and install software".
    • Pick "Install security updates automatically".
    • For "popularity-contest", pick "No".
    • For "Software selection", disable "Debian desktop environment" and "GNOME", and enable "SSH server".
  • Pick "Install the GRUB boot loader".
    • For "Run os-prober automatically", choose "No".
    • For "Install the GRUB boot loader to your primary drive", choose "Yes".
      • Choose "/dev/vda".
  • Pick "Finish the installation".
    • For "Is the system clock set to UTC", choose "Yes".
    • Choose "<Continue>" to reboot.
• SSH should exit.
  • Close and reopen the terminal, or run reset, to clean up the mess left by the debian installer.
• Wait until the VM has finished rebooting, then in the VM window, login as root with the password you set before:
  • Run apt install sudo git htop.
  • Create a non-root user now, but (this is important) you must avoid UID/GID 1000 since that will be used by the git user:
    • Run adduser --uid 1001 jacob (you can substitute jacob with whatever username you like.) Pick a suitable password, you can leave the other information blank if you like.
    • Run adduser jacob sudo. (substitute jacob with the username you picked.)
    • Press Ctrl+D to logout.
• On your host:
  • Copy your SSH public key(s) on the host to the VM:
    • Run scp ~/.ssh/id_*.pub jacob@libre-chip.test:. (substitute jacob with the username you picked.)
  • Run ssh jacob@libre-chip.test. (substitute jacob with the username you picked.)
  • Verify you don't have UID 1000 or GID 1000 by running id, it should say something like uid=1001(jacob) gid=1001(jacob).
  • Install the SSH public key(s) as allowed to login to the VM without a password:

    mkdir -p -m700 ~/.ssh
    cat id_*.pub > ~/.ssh/authorized_keys
    chmod 600 ~/.ssh/authorized_keys
    sudo mkdir -p -m700 /root/.ssh
    sudo install -m600 ~/.ssh/authorized_keys /root/.ssh/
    

  • Press Ctrl+D to logout.
  • Verify you can login as root without a password:
    • Run ssh root@libre-chip.test id, you shouldn't need any password and it should say uid=0(root) gid=0(root) groups=0(root). If you do need a password to unlock your SSH key, you need to have a running copy of ssh-agent and need your SSH key to be loaded.
• Now we create the snapshot:
  • Verify the VM is still running and that nothing is logged-in to the VM. (if you just rebooted the VM, login via SSH and then logout to ensure all the necessary system stuff has finished booting.)
  • Go to "View"/"Snapshots" in the VM's window in virt-manager.
  • Click the "+" button to create a new snapshot.
  • Name the snapshot start. (this is important)
  • Click "Finish".

Now you're ready to test! Just run ./test-in-vm.sh on the host, it will automatically reset the VM and login over ssh and run the setup script.

Installing on the public server

Make sure the VM has no users with UID 1000, and that the VM has a btrfs root filesystem.

Run the setup script on the VM:

sudo ./setup.sh --production