Table of Contents
If you don’t have an existing repository, choose the bootstrapping method. If you do have one you want to integrate with Skarabox, follow the Add in Existing Repo method.
The installation procedure can be followed on a VM, to test the installation process, on an on-premise server or on a cloud instance. For the first option, this flake template will create a suitable VM to test on and for the second, an ISO file will be produced that you can install on a USB stick and boot from on your on-premise server.
Finally, run the installer.
Following the installation procedure on a server WILL ERASE THE CONTENT of any disk on that server. Take the time to remove any disk you care about.
Create a directory and download the template.
$ mkdir myskarabox
$ cd myskarabox
$ nix run github:ibizaman/skarabox?ref=1.0.1#init
This last command will also generate the needed secrets
and ask for the password you want for the admin user
for a host named myskarabox whose files are located
under the myskarabox folder.
All the files at the root of this new repository are common to all hosts.
It will finally ask you to fill out two files: ./ip and ./system: and afterwards generate ./known_hosts. This will be done in Step B.
::: {.info} For a concrete example, look at the commit history of this repo which shows how to add a host managed by Skarabox to a repository using nix-starter-configs. :::
Add inputs:
inputs = {
nixpkgs.url = "github:nixos/nixpkgs/nixos-unstable";
skarabox.url = "github:ibizaman/skarabox";
nixos-generators.url = "github:nix-community/nixos-generators";
nixos-generators.inputs.nixpkgs.follows = "nixpkgs";
nixos-anywhere.url = "github:nix-community/nixos-anywhere";
nixos-anywhere.inputs.nixpkgs.follows = "nixpkgs";
nixos-facter-modules.url = "github:numtide/nixos-facter-modules";
flake-parts.url = "github:hercules-ci/flake-parts";
deploy-rs.url = "github:serokell/deploy-rs";
sops-nix.url = "github:Mic92/sops-nix";
};
Transform the outputs in a flake-parts module like outlined in the official tutorial.
In short:
Add mkFlake around the outputs attrset:
outputs = inputs@{ self, skarabox, sops-nix, nixpkgs, flake-parts, ... }: flake-parts.lib.mkFlake { inherit inputs; } (let
in {
});
Add the systems you want to handle:
systems = [
"x86_64-linux"
"aarch64-linux"
];
Import Skarabox’ flake module:
imports = [
skarabox.flakeModules.default
];
Add NixOS module importing your configuration.
flake = {
nixosModules = {
myskarabox = {
imports = [
./myskarabox/configuration.nix
];
};
};
};
Add a Skarabox managed host, here called myskarabox
that uses the above NixOS module:
skarabox.hosts = {
myskarabox = {
system = "x86_64-linux";
hostKeyPub = ./myskarabox/host_key.pub;
ip = ./myskarabox/ip;
sshPublicKey = ./myskarabox/ssh.pub;
knownHosts = ./myskarabox/known_hosts;
modules = [
sops-nix.nixosModules.default
self.nixosModules.myskarabox
];
};
};
Create Sops main key sops.key if needed:
nix run .#sops-create-main-key.
Add Sops main key to Sops config .sops.yaml:
nix run .#sops-add-main-key.
Create config for host myskarabox in folder ./myskarabox:
nix run .#gen-new-host myskarabox.
Tweak ./myskarabox/configuration.nix to change for example the username. The username will also be used as the user in the beacon.
Now, pick one of the Step B underneath.
Assuming the ./myskarabox/configuration.nix file is left untouched, you can now test the installation process on a VM. This VM has 3 hard drives, one for the OS and two in raid for the data.
To do that, first we tweak the ports to more sensible defaults for a VM:
$ echo 127.0.0.1 > ./myskarabox/ip
$ echo x86_64-linux > ./myskarabox/system
$ echo 2222 > ./myskarabox/ssh_port
$ echo 2223 > ./myskarabox/ssh_boot_port
Generate the known hosts file:
nix run .#myskarabox-gen-knownhosts-file
Then, start the VM:
$ nix run .#myskarabox-beacon-vm &
For info, this VM has 4 hard drives:
/dev/nvme0
/dev/nvme1
/dev/sda
/dev/sdb
Now, skip to step C.
This guide assumes you know how to boot your server on a USB stick.
Setup IP and system.
$ echo 192.168.1.30 > ./myskarabox/ip
$ echo x86_64-linux > ./myskarabox/system
$ nix run .#myskarabox-gen-knownhosts-file
Choose an IP that you can access in your network and the system that matches your server.
The IP used here will be statically assigned to the beacon and will be used to setup the WiFi hotspot from the beacon, if a WiFi card is enabled. Having a same IP for all makes the installation procedure much easier.
You can also setup a static IP for the server itself by enabling
the skarabox.staticNetwork option in your ./myskarabox/configuration.nix file.
Create the .iso file.
$ nix build .#myskarabox-beacon
Copy the .iso file to a USB key. This WILL ERASE THE CONTENT of the USB key.
$ nix run .#beacon-usbimager
Select ./result/iso/beacon.iso file in row 1 (...).
Select USB key in row 3.
Click write (arrow down) in row 2.
Plug the USB stick in the server. Choose to boot on it.
You will be logged in automatically with the user skarabox.username.
Note down the IP address and disk layout of the server.
For that, follow the steps that appeared when booting on the USB stick.
To reprint the steps, run the command skarabox-help.
Open the ./myskarabox/configuration.nix file and tweak values to match your hardware.
No need for the beacon here. As long as you can boot the instance, nixos-anywhere will take care of installing NixOS on it. For Hetzner for example, you can start in recovery mode.
Retrieve the IP of the server, then:
echo <ip> > myskarabox/ip
echo x86_64-linux > myskarabox/system
nix run .#myskarabox-gen-knownhosts-file
Replace the system with the correct one for your instance.
Create a ./myskarabox/facter.json file containing
the hardware specification of the host (or the VM) with:
$ nix run .#myskarabox-get-facter > ./myskarabox/facter.json
Add the ./myskarabox/facter.json to git (run git add ./myskarabox/facter.json).
Optionally, if you want to see exactly what nixos-facter did find
and will configure, run one or both of:
$ nix run .#myskarabox-debug-facter-nix-diff
$ nix run .#myskarabox-debug-facter-nvd
Now, run the installation process on the host:
$ nix run .#myskarabox-install-on-beacon
The server will reboot into NixOS on its own. Upon booting, the root partition will need to be decrypted as outlined in the next section.
These items act as a checklist that you should go through to make sure your installation is robust. How to proceed with each item is highly dependent on which hardware you have so it is hard for Skarabox to give a detailed explanation here.
Get your external IP Address by connecting to your home network and going to https://api.ipify.org/.
Buy a cheap domain name. I recommend https://porkbun.com/ because I use it and know it works but others work too.
Configure the domain’s DNS entries to have:
A record: Your domain name to your external IP Address.
A record: * (yes, a literal “asterisk”) to your external IP Address.
To check if this setup works, you will first need to go through the step below too.
These items should happen on your router.
Usually, connecting to it is done by entering one of the following IP addresses in your browser: 192.168.1.1 or 192.168.1.254.
Reduce the DHCP pool to the bounds .100 to .200, inclusive. This way, you are left with some space to statically allocate some IPs.
Statically assign the IP address of the server.
Enable port redirection for ports to the server IP:
80 to 80.
443 to 443.
A random port to 22 to be able to ssh into your server from abroad.
A random port to 2222 to be able to start the server from abroad.
To check if this setup works,
you can connect to another network (like using the tethered connection from your phone or connecting to another WiFi network)
and then ssh into your server like above,
but instead of using the IP address, use the domain name in ./ip.
I do recommend using the sibling project Self Host Blocks to setup services like Vaultwarden, Nextcloud and others.