commit 215a832d77f4831b0ef1d55c16992cb39202c5e6 · ryan.freumh.org/eilean-nix

+9 -32

README.md

···

       1
       1
       -
       Warning: work in progress.

     

       2
       1
        
       

     

       3
       3
       -
       # Eilean

     

       2
       2
       +
       # Eilean 🏝️

     

       4
       3
        
       

     

       5
       5
       -
       Create your own digital island powered by Nix.

     

       4
       4
       +
       Eilean enables you to host your own digital 'island', where you control you're own online infrastructure.

     

       5
       5
       +
       The use of federated protocols allows you to 'bridge' your island to others.

     

       6
       6
        
       

     

       7
       7
       -
       Self hosting is hard.

     

       8
       8
       -
       There's a lot of complexity to manage.

     

       7
       7
       +
       Eilean uses [NixOS](https://nixos.org/) to enable reproducible deployments of services such as webservers, mailservers, federated communication servers, Virtual Private Network servers, and more.

     

       8
       8
       +
       However, they still require a lot of manual configuration for domain names, DNS records, user accounts, databases, HTTP proxies, TLS certificates, and more.

     

       9
       9
        
       

     

       10
       10
       -
       While NixOS enables reproducible deployments of many services, they still require much manual configuration.

     

       11
       11
       -
       Adding domain names, DNS records, user accounts, databases, HTTP proxies, SMTP servers all add additional complexity.

     

       12
       12
       -
       

     

       13
       13
       -
       Eilean aims to be a personal or community 'island in a box' that requires minimal configuration.

     

       14
       14
       -
       It can achieve this by sharing configration between many NixOS modules (each for an individuial service).

     

       10
       10
       +
       Eilean aims to be a optioned framework to allow the simple deployment of these services on a single machine, and a library of documentation for common issues in managing runtime state like secrets, databases, and upgrades.

     

       15
       11
        
       

     

       16
       16
       -
       ### Usage

     

       12
       12
       +
       By using Nix Eilean modules are extensive to other configurations outside this deployment scenario, such as offloading a particularly resource heavy service to a dedicated machine.

     

       17
       13
        
       

     

       18
       18
       -
       Some familiarity with Nix is required. 

     

       14
       14
       +
       Contributions for additional services welcome.

     

       19
       15
        
       

     

       20
       20
       -
       TODO...

     

       21
       21
       -
       

     

       22
       22
       -
       ##### Networking

     

       23
       23
       -
       

     

       24
       24
       -
       Requires a public IPv4 and IPv6 address.

     

       25
       25
       -
       

     

       26
       26
       -
       ##### DNS

     

       27
       27
       -
       

     

       28
       28
       -
       Hosting DNS allows necessary records to be specified decleratively and enabled when the module that required then is.

     

       29
       29
       -
       You will need to point your domain's NS record to your IP address with your registar using a glue record.

     

       30
       30
       -
       

     

       31
       31
       -
       need to update SOA serial No

     

       32
       32
       -
       

     

       33
       33
       -
       ##### Email

     

       34
       34
       -
       

     

       35
       35
       -
       Hosting email allows for an easy, and cheap, SMTP server for services that require it.

     

       36
       36
       -
       Recieving EMail shouldn't pose an issues.

     

       37
       37
       -
       Sending 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.

     

       38
       38
       -
       Sending 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)).

     

       39
       39
       -
       

     

       16
       16
       +
       For instructions on getting started see [docs/getting_started.md](./docs/getting_started.md).

docs/adding_eilean.md

···

       1
       1
       +
       

     

       2
       2
       +
       # Adding Eilean to an Existing NixOS System

     

       3
       3
       +
       

     

       4
       4
       +
       If you already have a NixOS system and want to use Eilean you can add to your configuration.

     

       5
       5
       +
       Note this requires a flake-enabled system.

     

       6
       6
       +
       

     

       7
       7
       +
       Add `github:RyanGibb/eilean-nix` as an input to your flake, and import `eilean.nixosModules.default`.

     

       8
       8
       +
       You should then be able to use the configuration options in `config.eilean`.

     

       9
       9
       +
       See [../template/flake.nix](../template/flake.nix) for an example.

+199

docs/getting_started.md

···

       1
       1
       +
       

     

       2
       2
       +
       # Setup

     

       3
       3
       +
       

     

       4
       4
       +
       This guide walks a user through the first time setup of a server running Eilean.

     

       5
       5
       +
       If you already have a NixOS system, please feel look at [adding eilean](adding_eilean.md) to an existing system.

     

       6
       6
       +
       Some familiarity with networking, operating systems, and Linux is necessary.

     

       7
       7
       +
       Some familiarity with Nix is beneficial.

     

       8
       8
       +
       

     

       9
       9
       +
       ## Step 1: Find a server

     

       10
       10
       +
       

     

       11
       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].

     

       12
       12
       +
       You can use this referral link to get started on Hetzner: https://hetzner.cloud/?ref=XydbkWdf49TY.

     

       13
       13
       +
       

     

       14
       14
       +
       - Option 2: your own hardware, such as an old PC or laptop, Raspberry Pi, or a custom-build server.

     

       15
       15
       +
       Note 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
       16
       +
       

     

       17
       17
       +
       The resource requirements depend on the number of services you want to run and 

     

       18
       18
       +
       resource requirements

     

       19
       19
       +
       under 10G disk space with no services...

     

       20
       20
       +
       with all enabled...

     

       21
       21
       +
       

     

       22
       22
       +
       

     

       23
       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
       24
       +
       

     

       25
       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
       26
       +
       

     

       27
       27
       +
       Resource 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
       28
       +
       

     

       29
       29
       +
       ## Step 2: Install NixOS with Eilean

     

       30
       30
       +
       

     

       31
       31
       +
       Most service providers don't offer a NixOS image, so we'll install it manually.

     

       32
       32
       +
       

     

       33
       33
       +
       - Create the server with a generic linux distribution such as Debian.

     

       34
       34
       +
       - Mount the NixOS ISO, either from your provider directly, or by uploading it yourself. For Herzner:

     

       35
       35
       +
           - Create a new instance and power it off

     

       36
       36
       +
           - Switch to the ISO-Images tab and mount the NixOS minimal ISO

     

       37
       37
       +
           - Open the remote console (>_ button) and power the machine on

     

       38
       38
       +
           - Follow the usual installation guide

     

       39
       39
       +
           - Unmount the ISO and reboot

     

       40
       40
       +
       - Install NixOS.

     

       41
       41
       +
       

     

       42
       42
       +
       The [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
       43
       +
       ```

     

       44
       44
       +
       DISK=/dev/sda

     

       45
       45
       +
       

     

       46
       46
       +
       parted $DISK -- mklabel gpt

     

       47
       47
       +
       parted $DISK -- mkpart ESP fat32 1MB 512MB

     

       48
       48
       +
       parted $DISK -- mkpart primary 512MiB 100%

     

       49
       49
       +
       parted $DISK -- set 1 esp on

     

       50
       50
       +
       mkfs.fat -F 32 -n boot ${DISK}1

     

       51
       51
       +
       mkfs.ext4 -L nixos ${DISK}2

     

       52
       52
       +
       ```

     

       53
       53
       +
       

     

       54
       54
       +
       We can then mount the primary and boot partions and generate a configuration for you (possible virtualised) hardware:

     

       55
       55
       +
       ```

     

       56
       56
       +
       mount /dev/disk/by-label/nixos /mnt

     

       57
       57
       +
       mkdir /mnt/boot

     

       58
       58
       +
       mount /dev/disk/by-label/boot /mnt/boot

     

       59
       59
       +
       nixos-generate-config --root /mnt

     

       60
       60
       +
       ```

     

       61
       61
       +
       

     

       62
       62
       +
       It's possible to install Nix with the default configuration at this point.

     

       63
       63
       +
       However, Eilean comes with a simple template that's recommended to get you started:

     

       64
       64
       +
       ```

     

       65
       65
       +
       cd /mnt/etc/nixos

     

       66
       66
       +
       rm configuration.nix

     

       67
       67
       +
       nix flake init -t github:RyanGibb/eilean-nix

     

       68
       68
       +
       ```

     

       69
       69
       +
       

     

       70
       70
       +
       Note that we are using the `hardware-configuration.nix` generated by `nixos-generate-config`.

     

       71
       71
       +
       

     

       72
       72
       +
       Eilean uses [flakes](https://www.tweag.io/blog/2020-05-25-flakes/).

     

       73
       73
       +
       Without going into too much depth, they enable hermetic evaluation of Nix expressions and provide a standard way to compose Nix projects^[3].

     

       74
       74
       +
       

     

       75
       75
       +
       [3]: [tweag.io/blog/2020-05-25-flakes](https://www.tweag.io/blog/2020-05-25-flakes/).

     

       76
       76
       +
       

     

       77
       77
       +
       You can edit the resulting `configuration.nix`.

     

       78
       78
       +
       Check out the `TODO`'s for a place to start.

     

       79
       79
       +
       The 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.

     

       80
       80
       +
       One thing you should do at this point is generate a password hash with `mkpasswd` and add it to `root.initialHashedPassword`.

     

       81
       81
       +
       

     

       82
       82
       +
       Now, we can install NixOS and reboot:

     

       83
       83
       +
       ```

     

       84
       84
       +
       nixos-install --root /mnt/ --flake /mnt/etc/nixos#eilean --no-root-passwd

     

       85
       85
       +
       reboot

     

       86
       86
       +
       ```

     

       87
       87
       +
       

     

       88
       88
       +
       Upon boot you should be able to login as root.

     

       89
       89
       +
       You may need to run `passwd <username>` (where `<username>` is `eilean` by default) to be able to log in as `<username>`^[4].

     

       90
       90
       +
       You should be able to edit `/etc/nixos/configuration.nix` and rebuild you system with `sudo nixos-rebuild switch`.

     

       91
       91
       +
       

     

       92
       92
       +
       [4]: [github.com/NixOS/nixpkgs/issues/55424](https://github.com/NixOS/nixpkgs/issues/55424)

     

       93
       93
       +
       

     

       94
       94
       +
       By 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.

     

       95
       95
       +
       For example a Hetzner VPS IPv6 address can be found in the networking tab and enabled with:

     

       96
       96
       +
       ```

     

       97
       97
       +
         networking = {

     

       98
       98
       +
           interfaces."enp1s0" = {

     

       99
       99
       +
             ipv6.addresses = [{

     

       100
       100
       +
               address = "<address>";

     

       101
       101
       +
               prefixLength = 64;

     

       102
       102
       +
             }];

     

       103
       103
       +
           };

     

       104
       104
       +
           defaultGateway6 = {

     

       105
       105
       +
             address = "fe80::1";

     

       106
       106
       +
             interface = "enp1s0";

     

       107
       107
       +
           };

     

       108
       108
       +
         };

     

       109
       109
       +
       ```

     

       110
       110
       +
       

     

       111
       111
       +
       Replace `enp1s0` with your network interface (try `ip addr`).

     

       112
       112
       +
       

     

       113
       113
       +
       It's recommended to track `/etc/nixos` in a git repository.

     

       114
       114
       +
       Note that untracked files aren't seen by Nix flakes, so `git add` any new files you create to use them in Nix.

     

       115
       115
       +
       It may be useful to change the user and group from root so your user account can edit these files:

     

       116
       116
       +
       ```

     

       117
       117
       +
       sudo chgrp -R eilean /etc/nixos

     

       118
       118
       +
       sudo chgrp -R users /etc/nixos

     

       119
       119
       +
       ```

     

       120
       120
       +
       

     

       121
       121
       +
       Eilean creates a set of NixOS modules under `eilean`.

     

       122
       122
       +
       Check out the default configuration, and files in [modules](../modules/), to see what options there are.

     

       123
       123
       +
       (Documentation and man pages are on the way).

     

       124
       124
       +
       

     

       125
       125
       +
       ## Step 3: Get a Domain

     

       126
       126
       +
       

     

       127
       127
       +
       From your favourite registrar, e.g. [gandi.net](https://www.gandi.net/), purchase a domain.

     

       128
       128
       +
       Eilean automates Domain Name System (DNS) record creation and maintence by hosting DNS on the server and managing records decleratively.

     

       129
       129
       +
       

     

       130
       130
       +
       Create a Glue record with your registrar with `ns1.<domain>` pointing to your public IP address from step 1.

     

       131
       131
       +
       Next, add this as an external nameserver.

     

       132
       132
       +
       

     

       133
       133
       +
       If your domain TLD requires two nameservers, you can create a duplicate `ns2.<domain>`.

     

       134
       134
       +
       If you use a domain name other than this pattern, be sure to update `eilean.dns.nameservers`.

     

       135
       135
       +
       

     

       136
       136
       +
       You may need to wait up to 24 hours for DNS records to propagate at this point.

     

       137
       137
       +
       

     

       138
       138
       +
       You can check if this is working with:

     

       139
       139
       +
       ```

     

       140
       140
       +
       dig <domain>

     

       141
       141
       +
       ```

     

       142
       142
       +
       

     

       143
       143
       +
       ## Step 4: Configure Eilean

     

       144
       144
       +
       

     

       145
       145
       +
       Once your domain is setup, replace these default values of Eilean with your IPv4 and IPv6 network addresses, and your public network interface:

     

       146
       146
       +
       ```

     

       147
       147
       +
         eilean.serverIpv4 = "203.0.113.0";

     

       148
       148
       +
         eilean.serverIpv6 = "2001:DB8:0:0:0:0:0:0";

     

       149
       149
       +
         eilean.publicInterface = "enp1s0";

     

       150
       150
       +
       ```

     

       151
       151
       +
       

     

       152
       152
       +
       You should be able to get these from `ip addr`.

     

       153
       153
       +
       

     

       154
       154
       +
       Set `eilean.username` to what you want your username to be on email, matrix, and any other services.

     

       155
       155
       +
       A first name might be a good choice.

     

       156
       156
       +
       

     

       157
       157
       +
       Now, enable services at will!

     

       158
       158
       +
       It'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
       159
       +
       

     

       160
       160
       +
       ## Further Information 

     

       161
       161
       +
       

     

       162
       162
       +
       ### Website

     

       163
       163
       +
       

     

       164
       164
       +
       TODO

     

       165
       165
       +
       

     

       166
       166
       +
       ### Secrets

     

       167
       167
       +
       

     

       168
       168
       +
       TODO

     

       169
       169
       +
       

     

       170
       170
       +
       ### Backups

     

       171
       171
       +
       

     

       172
       172
       +
       TODO

     

       173
       173
       +
       

     

       174
       174
       +
       ##### Email

     

       175
       175
       +
       

     

       176
       176
       +
       Hosting email allows for an easy, and cheap, SMTP server for services that require it.

     

       177
       177
       +
       Receiving EMail shouldn't pose an issues.

     

       178
       178
       +
       Sending 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.

     

       179
       179
       +
       Sending 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
       180
       +
       

     

       181
       181
       +
       not managed:

     

       182
       182
       +
       - multiple domains

     

       183
       183
       +
       - multiple servers /load balance

     

       184
       184
       +
       

     

       185
       185
       +
       ### Matrix

     

       186
       186
       +
       

     

       187
       187
       +
       TODO

     

       188
       188
       +
       

     

       189
       189
       +
       ### Mastodon

     

       190
       190
       +
       

     

       191
       191
       +
       TODO

     

       192
       192
       +
       

     

       193
       193
       +
       ### Gitea

     

       194
       194
       +
       

     

       195
       195
       +
       TODO

     

       196
       196
       +
       

     

       197
       197
       +
       ### Wireguard/Headscale

     

       198
       198
       +
       

     

       199
       199
       +
       TODO

+83

docs/nix.md

···

       1
       1
       +
       

     

       2
       2
       +
       # Nix

     

       3
       3
       +
       

     

       4
       4
       +
       Nix is a software deployment system that uses cryptographic hashes to compute unique paths for components (i.e., packages) that are stored in a read-only directory: the Nix store, at `/nix/store/<hash>-<name>`.

     

       5
       5
       +
       This provides several benefits, including concurrent installation of multiple versions of a package, atomic upgrades, and multiple user environments.

     

       6
       6
       +
       

     

       7
       7
       +
       Nix uses a declarative domain-specific language (DSL), also called Nix, to build and configure software.

     

       8
       8
       +
       The Nix DSL is a functional language with a syntax Turing complete but lacks a type system.

     

       9
       9
       +
       We use the DSL to write derivations for software, which describe how to build said software with input components and a build script.

     

       10
       10
       +
       This Nix expression is then 'instantiated' to create 'store derivations' (`.drv` files), which is the low-level representation of how to build a single component.

     

       11
       11
       +
       This store derivation is 'realised' into a built artefact, hereafter referred to as 'building'.

     

       12
       12
       +
       

     

       13
       13
       +
       Possibly the simplest Nix derivation uses `bash` to create a single file containing `Hello, World!`:

     

       14
       14
       +
       ```nix

     

       15
       15
       +
       { pkgs ? import <nixpkgs> {  } }:

     

       16
       16
       +
       

     

       17
       17
       +
       builtins.derivation {

     

       18
       18
       +
         name = "hello";

     

       19
       19
       +
         system = builtins.currentSystem;

     

       20
       20
       +
         builder = "${nixpkgs.bash}/bin/bash";

     

       21
       21
       +
         args = [ "-c" ''echo "Hello, World!" > $out'' ];

     

       22
       22
       +
       }

     

       23
       23
       +
       ```

     

       24
       24
       +
       Note that `derivation` is a function that we're calling with one argument, which is a set of attributes.

     

       25
       25
       +
       

     

       26
       26
       +
       We can instantiate this Nix derivation to create a store derivation:

     

       27
       27
       +
       ```

     

       28
       28
       +
       $ nix-instantiate default.nix

     

       29
       29
       +
       /nix/store/5d4il3h1q4cw08l6fnk4j04a19dsv71k-hello.drv

     

       30
       30
       +
       $ nix show-derivation /nix/store/5d4il3h1q4cw08l6fnk4j04a19dsv71k-hello.drv

     

       31
       31
       +
       {

     

       32
       32
       +
         "/nix/store/5d4il3h1q4cw08l6fnk4j04a19dsv71k-hello.drv": {

     

       33
       33
       +
           "outputs": {

     

       34
       34
       +
             "out": {

     

       35
       35
       +
               "path": "/nix/store/4v1dx6qaamakjy5jzii6lcmfiks57mhl-hello"

     

       36
       36
       +
             }

     

       37
       37
       +
           },

     

       38
       38
       +
           "inputSrcs": [],

     

       39
       39
       +
           "inputDrvs": {

     

       40
       40
       +
             "/nix/store/mnyhjzyk43raa3f44pn77aif738prd2m-bash-5.1-p16.drv": [

     

       41
       41
       +
               "out"

     

       42
       42
       +
             ]

     

       43
       43
       +
           },

     

       44
       44
       +
           "system": "x86_64-linux",

     

       45
       45
       +
           "builder": "/nix/store/2r9n7fz1rxq088j6mi5s7izxdria6d5f-bash-5.1-p16/bin/bash",

     

       46
       46
       +
           "args": [ "-c", "echo \"Hello, World!\" > $out" ],

     

       47
       47
       +
           "env": {

     

       48
       48
       +
             "builder": "/nix/store/2r9n7fz1rxq088j6mi5s7izxdria6d5f-bash-5.1-p16/bin/bash",

     

       49
       49
       +
             "name": "hello",

     

       50
       50
       +
             "out": "/nix/store/4v1dx6qaamakjy5jzii6lcmfiks57mhl-hello",

     

       51
       51
       +
             "system": "x86_64-linux"

     

       52
       52
       +
           }

     

       53
       53
       +
         }

     

       54
       54
       +
       }

     

       55
       55
       +
       ```

     

       56
       56
       +
       

     

       57
       57
       +
       And build the store derivation:

     

       58
       58
       +
       ```sh

     

       59
       59
       +
       $ nix-store --realise /nix/store/5d4il3h1q4cw08l6fnk4j04a19dsv71k-hello.drv

     

       60
       60
       +
       /nix/store/4v1dx6qaamakjy5jzii6lcmfiks57mhl-hello

     

       61
       61
       +
       $ cat /nix/store/4v1dx6qaamakjy5jzii6lcmfiks57mhl-hello

     

       62
       62
       +
       Hello, World!

     

       63
       63
       +
       ```

     

       64
       64
       +
       

     

       65
       65
       +
       Most Nix tooling does these two steps together:

     

       66
       66
       +
       ```

     

       67
       67
       +
       nix-build default.nix

     

       68
       68
       +
       this derivation will be built:

     

       69
       69
       +
         /nix/store/q5hg3vqby8a9c8pchhjal3la9n7g1m0z-hello.drv

     

       70
       70
       +
       building '/nix/store/q5hg3vqby8a9c8pchhjal3la9n7g1m0z-hello.drv'...

     

       71
       71
       +
       /nix/store/zyrki2hd49am36jwcyjh3xvxvn5j5wml-hello

     

       72
       72
       +
       ```

     

       73
       73
       +
       

     

       74
       74
       +
       Nix realisations (hereafter referred to as 'builds') are done in isolation to ensure reproducibility.

     

       75
       75
       +
       Projects often rely on interacting with package managers to make sure all dependencies are available and may implicitly rely on system configuration at build time.

     

       76
       76
       +
       To prevent this, every Nix derivation is built in isolation (without network access or access to the global file system) with only other Nix derivations as inputs.

     

       77
       77
       +
       

     

       78
       78
       +
       > The name Nix is derived from the Dutch word *niks*, meaning nothing; build actions do not see anything that has not been explicitly declared as an input.

     

       79
       79
       +
       

     

       80
       80
       +
       For more information, see:

     

       81
       81
       +
       - The Nix paper: https://edolstra.github.io/pubs/nspfssd-lisa2004-final.pdf

     

       82
       82
       +
       - The Nix PhD thesis: https://edolstra.github.io/pubs/phd-thesis.pdf

     

       83
       83
       +

+19

docs/nixos.md

···

       1
       1
       +
       

     

       2
       2
       +
       # NixOS

     

       3
       3
       +
       

     

       4
       4
       +
       [NixOS](nixos.org) is a Linux distribution built with [Nix](./nix.md) from a modular, purely functional specification.

     

       5
       5
       +
       It has no traditional filesystem hierarchy (FSH), like `/bin`, `/lib`, `/usr`, but instead stores all components in `/nix/store`.

     

       6
       6
       +
       The system configuration is managed by Nix and configured with Nix expressions.

     

       7
       7
       +
       [NixOS modules](https://nixos.org/manual/nixos/stable/index.html#sec-writing-modules) are Nix files containing chunks of system configuration that can be composed to build a full NixOS system.

     

       8
       8
       +
       While many NixOS modules are provided in the [Nixpkgs](./nixpkgs.md) repository, they can also be written by an individual user.

     

       9
       9
       +
       For example, the expression used to deploy a DNS server is a NixOS module.

     

       10
       10
       +
       Together these modules form the configuration which builds the Linux system as a Nix derivation.

     

       11
       11
       +
       

     

       12
       12
       +
       NixOS minimises global mutable state that -- without knowing it -- you might rely on being set up in a certain way.

     

       13
       13
       +
       For example, you might follow instructions to run a series of shell commands and edit some files to get a piece of software working.

     

       14
       14
       +
       You may subsequently be unable to reproduce the result because you've forgotten some intricacy or are now using a different version of the software.

     

       15
       15
       +
       Nix forces you to encode this in a reproducible way, which is extremely useful for replicating software configurations and deployments, aiming to solve the 'It works on my machine' problem.

     

       16
       16
       +
       Docker is often used to fix this configuration problem, but Nix aims to be more reproducible.

     

       17
       17
       +
       

     

       18
       18
       +
       Nix provides safe and reliable atomic upgrades and rollbacks.

     

       19
       19
       +
       And every new system configuration build creates a GRUB entry, so you can boot previous systems even from your UEFI/BIOS.

+19

docs/nixpkgs.md

···

       1
       1
       +
       

     

       2
       2
       +
       ### Nixpkgs

     

       3
       3
       +
       

     

       4
       4
       +
       Nixpkgs^[ [github.com/nixos/nixpkgs](https://github.com/nixos/nixpkgs) ] is a large repository of software packaged in [Nix](./nix.md), where every package is a Nix derivation.

     

       5
       5
       +
       It also stores all the default [./NixOS](./nixos.md) modules.

     

       6
       6
       +
       

     

       7
       7
       +
       There is also a command line package manager that installs packages from Nixpkgs, which is why people sometimes refer to Nix as a package manager.

     

       8
       8
       +
       

     

       9
       9
       +
       While Nix, and therefore Nix package management, is primarily source-based (since derivations describe how to build software from source), binary deployment is an optimisation of this.

     

       10
       10
       +
       Since packages are built in isolation and entirely determined by their inputs, binaries can be transparently deployed by downloading them from a remote server instead of building the derivation locally.

     

       11
       11
       +
       

     

       12
       12
       +
       Nix supports atomic upgrades and rollbacks.

     

       13
       13
       +
       The pointers to the new packages are only updated when the install succeeds.

     

       14
       14
       +
       

     

       15
       15
       +
       Due to every

     

       16
       16
       +
       

     

       17
       17
       +
       

     

       18
       18
       +
       While Nixpkgs also has one global coherent package set, one can use multiple instances of Nixpkgs (i.e., channels) at once to support partial upgrades, as the Nix store allows multiple versions of a dependency to be stored.

     

       19
       19
       +
       This also supports atomic upgrades, as all the software's old versions can be kept until garbage collection.

+9 -7

template/configuration.nix

···

       54
       54
        
       

     

       55
       55
        
         eilean = {

     

       56
       56
        
           # TODO replace these values

     

       57
       57
       -
           username = "user";

     

       58
       58
       -
           secretsDir = "/secrets";

     

       59
       59
       -
           serverIpv4 = "203.0.113.0";

     

       60
       60
       -
           serverIpv6 = "2001:DB8:0:0:0:0:0:0";

     

       61
       61
       -
           publicInterface = "enp1s0";

     

       57
       57
       +
           # serverIpv4 = "203.0.113.0";

     

       58
       58
       +
           # serverIpv6 = "2001:DB8:0:0:0:0:0:0";

     

       59
       59
       +
           # publicInterface = "enp1s0";

     

       60
       60
       +
       

     

       61
       61
       +
           # TODO replace with your desired username

     

       62
       62
       +
           # username = "user";

     

       62
       63
        
       

     

       63
       64
        
           # TODO enable desired services

     

       64
       64
       -
           dns.enable = true;

     

       65
       65
        
           # mailserver.enable = true;

     

       66
       66
        
           # matrix.enable = true;

     

       67
       67
        
           # mastodon.enable = true;

     

       68
       68
        
           # gitea.enable = true;

     

       69
       69
       -
           # dns.enable = true;

     

       69
       69
       +
           # headscale.enable = true;

     

       70
       70
       +
       

     

       71
       71
       +
           # secretsDir = "/secrets";

     

       70
       72
        
         };

     

       71
       73
        
       

     

       72
       74
        
         # This value determines the NixOS release from which the default