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
24resource requirements
25under 10G disk space with no services...
26with all enabled...
27
28
29[1]: You could just use an IPv6 address, but much of the Internet is still [IPv4-only](https://stats.labs.apnic.net/ipv6).
30
31[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.
32
33Resource requirements depends how many service you want to run and how much load they'll be under, but 2 GB RAM and 20 GB disk should be a good starting point.
34
35## Step 2: Install NixOS with Eilean
36
37Most service providers don't offer a NixOS image, so we'll install it manually.
38
39- Create the server with a generic linux distribution such as Debian.
40- Mount the NixOS ISO, either from your provider directly, or by uploading it yourself. For Herzner:
41 - Create a new instance and power it off
42 - Switch to the ISO-Images tab and mount the NixOS minimal ISO
43 - Open the remote console (>_ button) and power the machine on
44 - Follow the usual installation guide
45 - Unmount the ISO and reboot
46- Install NixOS.
47
48The [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:
49```
50DISK=/dev/sda
51
52parted $DISK -- mklabel gpt
53parted $DISK -- mkpart ESP fat32 1MB 512MB
54parted $DISK -- mkpart primary 512MiB 100%
55parted $DISK -- set 1 esp on
56mkfs.fat -F 32 -n boot ${DISK}1
57mkfs.ext4 -L nixos ${DISK}2
58```
59
60We can then mount the primary and boot partions and generate a configuration for you (possible virtualised) hardware:
61```
62mount /dev/disk/by-label/nixos /mnt
63mkdir /mnt/boot
64mount /dev/disk/by-label/boot /mnt/boot
65nixos-generate-config --root /mnt
66```
67
68It's possible to install Nix with the default configuration at this point.
69However, Eilean comes with a simple template that's recommended to get you started:
70```
71cd /mnt/etc/nixos
72rm configuration.nix
73nix flake init -t github:RyanGibb/eilean-nix
74```
75
76Note that we are using the `hardware-configuration.nix` generated by `nixos-generate-config`.
77
78Eilean uses [flakes](https://www.tweag.io/blog/2020-05-25-flakes/).
79Without going into too much depth, they enable hermetic evaluation of Nix expressions and provide a standard way to compose Nix projects^[3].
80
81[3]: [tweag.io/blog/2020-05-25-flakes](https://www.tweag.io/blog/2020-05-25-flakes/).
82
83You can edit the resulting `configuration.nix`.
84Check out the `TODO`'s for a place to start.
85The 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.
86One thing you should do at this point is generate a password hash with `mkpasswd` and add it to `root.initialHashedPassword`.
87
88Now, we can install NixOS and reboot:
89```
90nixos-install --root /mnt/ --flake /mnt/etc/nixos#eilean --no-root-passwd
91reboot
92```
93
94Upon boot you should be able to login as root.
95You may need to run `passwd <username>` (where `<username>` is `eilean` by default) to be able to log in as `<username>`^[4].
96You should be able to edit `/etc/nixos/configuration.nix` and rebuild you system with `sudo nixos-rebuild switch`.
97
98[4]: [github.com/NixOS/nixpkgs/issues/55424](https://github.com/NixOS/nixpkgs/issues/55424)
99
100By default DHCP will be enabled so your machine will discovery it's IP address, however some providers don't enable DHCPv6 or SLAAC so you need to manually configure the IP address.
101For example a Hetzner VPS IPv6 address can be found in the networking tab and enabled with:
102```
103 networking = {
104 interfaces."enp1s0" = {
105 ipv6.addresses = [{
106 address = "<address>";
107 prefixLength = 64;
108 }];
109 };
110 defaultGateway6 = {
111 address = "fe80::1";
112 interface = "enp1s0";
113 };
114 };
115```
116
117Replace `enp1s0` with your network interface (try `ip addr`).
118
119It's recommended to track `/etc/nixos` in a git repository.
120Note that untracked files aren't seen by Nix flakes, so `git add` any new files you create to use them in Nix.
121It may be useful to change the user and group from root so your user account can edit these files:
122```
123sudo chgrp -R eilean /etc/nixos
124sudo chgrp -R users /etc/nixos
125```
126
127Eilean creates a set of NixOS modules under `eilean`.
128Check out the default configuration, and files in [modules](../modules/), to see what options there are.
129(Documentation and man pages are on the way).
130
131## Step 3: Get a Domain
132
133From your favourite registrar, e.g. [gandi.net](https://www.gandi.net/), purchase a domain.
134Eilean automates Domain Name System (DNS) record creation and maintence by hosting DNS on the server and managing records decleratively.
135
136Create a Glue record with your registrar with `ns1.<domain>` pointing to your public IP address from step 1.
137Next, add this as an external nameserver.
138
139If your domain TLD requires two nameservers, you can create a duplicate `ns2.<domain>`.
140If you use a domain name other than this pattern, be sure to update `eilean.dns.nameservers`.
141
142You may need to wait up to 24 hours for DNS records to propagate at this point.
143
144You can check if this is working with:
145```
146dig <domain>
147```
148
149## Step 4: Configure Eilean
150
151Once your domain is setup, replace these default values of Eilean with your IPv4 and IPv6 network addresses, and your public network interface:
152```
153 eilean.serverIpv4 = "203.0.113.0";
154 eilean.serverIpv6 = "2001:DB8:0:0:0:0:0:0";
155 eilean.publicInterface = "enp1s0";
156```
157
158You should be able to get these from `ip addr`.
159
160Set `eilean.username` to what you want your username to be on email, matrix, and any other services.
161A first name might be a good choice.
162
163Now, enable services at will!
164It'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.
165
166## Further Information
167
168See [docs](../docs/).