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.
5If you already have a NixOS system, please feel look at [adding eilean](adding_eilean.md) to an existing system.
6Some familiarity with networking, operating systems, and Linux is necessary.
7Some familiarity with Nix is beneficial.
8
9## Step 1: Find a server
10
11- Option 1 (recommended): a Virtual Private Server (VPS) with a cloud provider such as Hetzner, Vultr, or Digital Ocean. Get an IPv4 address^[1].
12You can use this referral link to get started on Hetzner: https://hetzner.cloud/?ref=XydbkWdf49TY.
13
14- Option 2: your own hardware, such as an old PC or laptop, Raspberry Pi, or a custom-build server.
15Note 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.
16
17The resource requirements depend on the number of services you want to run and
18resource requirements
19under 10G disk space with no services...
20with all enabled...
21
22
23[1]: You could just use an IPv6 address, but much of the Internet is still [IPv4-only](https://stats.labs.apnic.net/ipv6).
24
25[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.
26
27Resource 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.
28
29## Step 2: Install NixOS with Eilean
30
31Most service providers don't offer a NixOS image, so we'll install it manually.
32
33- Create the server with a generic linux distribution such as Debian.
34- Mount the NixOS ISO, either from your provider directly, or by uploading it yourself. For Herzner:
35 - Create a new instance and power it off
36 - Switch to the ISO-Images tab and mount the NixOS minimal ISO
37 - Open the remote console (>_ button) and power the machine on
38 - Follow the usual installation guide
39 - Unmount the ISO and reboot
40- Install NixOS.
41
42The [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:
43```
44DISK=/dev/sda
45
46parted $DISK -- mklabel gpt
47parted $DISK -- mkpart ESP fat32 1MB 512MB
48parted $DISK -- mkpart primary 512MiB 100%
49parted $DISK -- set 1 esp on
50mkfs.fat -F 32 -n boot ${DISK}1
51mkfs.ext4 -L nixos ${DISK}2
52```
53
54We can then mount the primary and boot partions and generate a configuration for you (possible virtualised) hardware:
55```
56mount /dev/disk/by-label/nixos /mnt
57mkdir /mnt/boot
58mount /dev/disk/by-label/boot /mnt/boot
59nixos-generate-config --root /mnt
60```
61
62It's possible to install Nix with the default configuration at this point.
63However, Eilean comes with a simple template that's recommended to get you started:
64```
65cd /mnt/etc/nixos
66rm configuration.nix
67nix flake init -t github:RyanGibb/eilean-nix
68```
69
70Note that we are using the `hardware-configuration.nix` generated by `nixos-generate-config`.
71
72Eilean uses [flakes](https://www.tweag.io/blog/2020-05-25-flakes/).
73Without going into too much depth, they enable hermetic evaluation of Nix expressions and provide a standard way to compose Nix projects^[3].
74
75[3]: [tweag.io/blog/2020-05-25-flakes](https://www.tweag.io/blog/2020-05-25-flakes/).
76
77You can edit the resulting `configuration.nix`.
78Check out the `TODO`'s for a place to start.
79The 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.
80One thing you should do at this point is generate a password hash with `mkpasswd` and add it to `root.initialHashedPassword`.
81
82Now, we can install NixOS and reboot:
83```
84nixos-install --root /mnt/ --flake /mnt/etc/nixos#eilean --no-root-passwd
85reboot
86```
87
88Upon boot you should be able to login as root.
89You may need to run `passwd <username>` (where `<username>` is `eilean` by default) to be able to log in as `<username>`^[4].
90You should be able to edit `/etc/nixos/configuration.nix` and rebuild you system with `sudo nixos-rebuild switch`.
91
92[4]: [github.com/NixOS/nixpkgs/issues/55424](https://github.com/NixOS/nixpkgs/issues/55424)
93
94By 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.
95For example a Hetzner VPS IPv6 address can be found in the networking tab and enabled with:
96```
97 networking = {
98 interfaces."enp1s0" = {
99 ipv6.addresses = [{
100 address = "<address>";
101 prefixLength = 64;
102 }];
103 };
104 defaultGateway6 = {
105 address = "fe80::1";
106 interface = "enp1s0";
107 };
108 };
109```
110
111Replace `enp1s0` with your network interface (try `ip addr`).
112
113It's recommended to track `/etc/nixos` in a git repository.
114Note that untracked files aren't seen by Nix flakes, so `git add` any new files you create to use them in Nix.
115It may be useful to change the user and group from root so your user account can edit these files:
116```
117sudo chgrp -R eilean /etc/nixos
118sudo chgrp -R users /etc/nixos
119```
120
121Eilean creates a set of NixOS modules under `eilean`.
122Check out the default configuration, and files in [modules](../modules/), to see what options there are.
123(Documentation and man pages are on the way).
124
125## Step 3: Get a Domain
126
127From your favourite registrar, e.g. [gandi.net](https://www.gandi.net/), purchase a domain.
128Eilean automates Domain Name System (DNS) record creation and maintence by hosting DNS on the server and managing records decleratively.
129
130Create a Glue record with your registrar with `ns1.<domain>` pointing to your public IP address from step 1.
131Next, add this as an external nameserver.
132
133If your domain TLD requires two nameservers, you can create a duplicate `ns2.<domain>`.
134If you use a domain name other than this pattern, be sure to update `eilean.dns.nameservers`.
135
136You may need to wait up to 24 hours for DNS records to propagate at this point.
137
138You can check if this is working with:
139```
140dig <domain>
141```
142
143## Step 4: Configure Eilean
144
145Once your domain is setup, replace these default values of Eilean with your IPv4 and IPv6 network addresses, and your public network interface:
146```
147 eilean.serverIpv4 = "203.0.113.0";
148 eilean.serverIpv6 = "2001:DB8:0:0:0:0:0:0";
149 eilean.publicInterface = "enp1s0";
150```
151
152You should be able to get these from `ip addr`.
153
154Set `eilean.username` to what you want your username to be on email, matrix, and any other services.
155A first name might be a good choice.
156
157Now, enable services at will!
158It'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.
159
160## Further Information
161
162### Website
163
164TODO
165
166### Secrets
167
168TODO
169
170### Backups
171
172TODO
173
174##### Email
175
176Hosting email allows for an easy, and cheap, SMTP server for services that require it.
177Receiving EMail shouldn't pose an issues.
178Sending email to users on your own domain shouldn't pose any issues, if for example users are signing up to services like Mastodon using an EMail account on the same Eilean.
179Sending mail will require TCP port 25 to be unblocked by your network provider, and your IP address to not be blacklisted (e.g. check [here](https://mxtoolbox.com/blacklists.aspx)).
180
181not managed:
182- multiple domains
183- multiple servers /load balance
184
185### Matrix
186
187TODO
188
189### Mastodon
190
191TODO
192
193### Gitea
194
195TODO
196
197### Wireguard/Headscale
198
199TODO