Self-host your own digital island
ryan.freumh.org
1
2# Setup
3
4This guide walks a user through the first time setup of a server running Eilean.
5
6If you already have a NixOS system and want to use Eilean you can add to your configuration.
7Note this requires a flake-enabled system.
8Add `github:RyanGibb/eilean-nix` as an input to your flake, and import `eilean.nixosModules.default`.
9You should then be able to use the configuration options in `config.eilean`.
10See [../template/flake.nix](../template/flake.nix) for an example.
11
12Otherwise, some familiarity with networking, operating systems, and Linux is necessary.
13And some familiarity with Nix is beneficial.
14
15## Step 1: Find a server
16
17- Option 1 (recommended): a Virtual Private Server (VPS) with a cloud provider such as Hetzner, Vultr, or Digital Ocean. Get an IPv4 address[^1].
18You can use this referral link to get started on Hetzner: https://hetzner.cloud/?ref=XydbkWdf49TY.
19
20- Option 2: your own hardware, such as an old PC or laptop, Raspberry Pi, or a custom-build server.
21Note you'll need a static IPv4[^1] address for reliable hosting[^2]. If you're behind Network Address Translation (NAT) you'll need to set up port forwarding for every service you want to run.
22
23The resource requirements depend on the number of services you want to run, and the load they'll be under.
24With no services 10 GiB of disk space and 1 GiB of RAM is plenty, though you may want to enable swap if you have low memory.
25With all services enabled and fairly populated databases 40 GiB of disk space and 2 GiB of RAM is appropriate.
26
27[^1]: You could just use an IPv6 address, but much of the Internet is still [IPv4-only](https://stats.labs.apnic.net/ipv6).
28
29[^2]: If you don't have a static address, Dynamic DNS is possible but takes some time to propagate. Email reputation is tied to your IP address; using a residential address assigned by your ISP may get your mail blocked.
30
31Resource requirements depend on how many services you want to run and how much load they'll be under, but 2 GiB RAM and 20 GiB disk should be a good starting point.
32
33## Step 2: Install NixOS with Eilean
34
35Most service providers don't offer a NixOS image, so we'll install it manually.
36
37- Create the server with a generic linux distribution such as Debian.
38- Mount the NixOS ISO, either from your provider directly, or by uploading it yourself. For Herzner:
39 - Create a new instance and power it off
40 - Switch to the ISO-Images tab and mount the NixOS minimal ISO
41 - Open the remote console (>_ button) and power the machine on
42 - Follow the usual installation guide
43 - Unmount the ISO and reboot
44- Install NixOS.
45
46The [official manual](https://nixos.org/manual/nixos/stable/index.html#sec-installation-manual) contains detailed instructions, but the minimum to get your disk partioned is:
47```
48DISK=/dev/sda
49
50parted $DISK -- mklabel gpt
51parted $DISK -- mkpart ESP fat32 1MB 512MB
52parted $DISK -- mkpart primary 512MiB 100%
53parted $DISK -- set 1 esp on
54mkfs.fat -F 32 -n boot ${DISK}1
55mkfs.ext4 -L nixos ${DISK}2
56```
57
58We can then mount the primary and boot partions and generate a configuration for you (possible virtualised) hardware:
59```
60mount /dev/disk/by-label/nixos /mnt
61mkdir /mnt/boot
62mount /dev/disk/by-label/boot /mnt/boot
63nixos-generate-config --root /mnt
64```
65
66It's possible to install Nix with the default configuration at this point.
67However, Eilean comes with a simple template that's recommended to get you started:
68```
69cd /mnt/etc/nixos
70rm configuration.nix
71nix flake init -t github:RyanGibb/eilean-nix
72```
73
74Note that we are using the `hardware-configuration.nix` generated by `nixos-generate-config`.
75
76Eilean uses [flakes](https://www.tweag.io/blog/2020-05-25-flakes/).
77Without going into too much depth, they enable hermetic evaluation of Nix expressions and provide a standard way to compose Nix projects[^3].
78
79[^3]: [tweag.io/blog/2020-05-25-flakes](https://www.tweag.io/blog/2020-05-25-flakes/).
80
81You can edit the resulting `configuration.nix`.
82Check out the `TODO`'s for a place to start.
83The website [search.nixos.org](https://search.nixos.org/) is a great place to find information on configuration options and packages available, and with `man 5 configuration.nix` you can see the configuration options locally.
84One thing you should do at this point is generate a password hash with `mkpasswd` and add it to `root.initialHashedPassword`.
85
86Now, we can install NixOS and reboot:
87```
88nixos-install --root /mnt/ --flake /mnt/etc/nixos#eilean --no-root-passwd
89reboot
90```
91
92Upon boot you should be able to login as root.
93You may need to run `passwd <username>` (where `<username>` is `eilean` by default) to be able to log in as `<username>`[^4].
94You should be able to edit `/etc/nixos/configuration.nix` and rebuild you system with `sudo nixos-rebuild switch`.
95
96[^4]: [github.com/NixOS/nixpkgs/issues/55424](https://github.com/NixOS/nixpkgs/issues/55424)
97
98By default, DHCP will be enabled, so your machine will discover its IP address, however some providers don't enable DHCPv6 or SLAAC, so you need to manually configure the IP address.
99For example a Hetzner VPS IPv6 address can be found in the networking tab and enabled with:
100```
101 networking = {
102 interfaces."enp1s0" = {
103 ipv6.addresses = [{
104 address = "<address>";
105 prefixLength = 64;
106 }];
107 };
108 defaultGateway6 = {
109 address = "fe80::1";
110 interface = "enp1s0";
111 };
112 };
113```
114
115Replace `enp1s0` with your network interface (try `ip addr`).
116
117It's recommended to track `/etc/nixos` in a git repository.
118Note that untracked files aren't seen by Nix flakes, so `git add` any new files you create to use them in Nix.
119It may be useful to change the user and group from root so your user account can edit these files:
120```
121sudo chgrp -R eilean /etc/nixos
122sudo chgrp -R users /etc/nixos
123```
124
125Eilean creates a set of NixOS modules under `eilean`.
126Check out the default configuration, and files in [modules](../modules/), to see what options there are.
127(Documentation and man pages are on the way).
128
129## Step 3: Get a Domain
130
131From your favourite registrar, e.g. [gandi.net](https://www.gandi.net/), purchase a domain.
132Eilean automates Domain Name System (DNS) record creation and maintence by hosting DNS on the server and managing records decleratively.
133
134Create a Glue record with your registrar with `ns1.<domain>` pointing to your public IP address from step 1.
135Next, add this as an external nameserver.
136
137If your domain TLD requires two nameservers, you can create a duplicate `ns2.<domain>`.
138If you use a domain name other than this pattern, be sure to update `eilean.dns.nameservers`.
139
140You may need to wait up to 24 hours for DNS records to propagate at this point.
141
142You can check if this is working with:
143```
144dig <domain>
145```
146
147## Step 4: Configure Eilean
148
149Once your domain is set up, replace these default values of Eilean with your IPv4 and IPv6 network addresses, and your public network interface:
150```
151 eilean.serverIpv4 = "203.0.113.0";
152 eilean.serverIpv6 = "2001:DB8:0:0:0:0:0:0";
153 eilean.publicInterface = "enp1s0";
154```
155
156You should be able to get these from `ip addr`.
157
158Set `eilean.username` to what you want your username to be on email, matrix, and any other services.
159A first name might be a good choice.
160
161Now, enable services at will!
162It's a good idea to enable one service at a time initially or else if you run into issues, e.g. DNS record propitiation, then you may get rate limited by Let's Encrypt for TLS certificate provisioning.
163
164## Further Information
165
166For a list of options, use `man eilean-configuration.nix`.
167