Initial commit

README.md

@@ -0,0 +1,159 @@
+# Nix scripts
+
+A collection of scripts and configuration files for our use of Nix tooling.
+
+## Setting up a new server
+
+This is just for getting a working NixOS installation with `/etc/nixos/configuration.nix` deployed onto a generic cloud VM.
+
+The setup also uses `/etc/nixos/flake.nix` since that's an easy way of addressing
+[the nixos-anywhere NIX_PATH issue](https://nix-community.github.io/nixos-anywhere/howtos/nix-path.html)
+and you likely want to use flakes anyway.
+
+**Note: All of the automated scripts for the steps below assume you're logging in as root**. If that's not the case, just follow
+the steps manually. The scripts will also create lockfiles in `anywhere/` and `postinstall/` to make future deployments consistent
+and faster (by reusing more things from your nix store). Feel free to delete those if you want a completely fresh install each time.
+
+This section is overall just a thin wrapper around nixos-anywhere.
+
+### Installing NixOS
+
+- Provision a new server. This config works on Hetzner Cloud, may require adjustments for other
+  providers, see anywhere/flake.nix
+    - The default config uses `aarch64`, you can change this to `x86_64`
+- Preferably use passwordless auth with just your SSH key
+
+> Cross-compilation is sometimes buggy so it's recommended to run this on Linux (use a NixOS VM if you're on macOS), preferably
+> matching the server's ISA. On macOS I highly recommend creating a NixOS VM (helpful for development anyway) in Parallels with
+> no desktop environment, ssh enabled, and shared folders.
+>
+> That said, running this on macOS *should* still work fine, again ideally on the same ISA as the server (hence the aarch64 default).
+
+Now either run `(cd anywhere && ./auto.sh <server_ip> <path_to_your_ssh_key>)`, with the path being e.g. `~/.ssh/id_ed25519.pub`. Or
+if you want to do this manually (or make customizations):
+- **Put the key into anywhere/configuration.nix (the REPLACEME) so you can log in after NixOS is installed**
+- Run `nix run nixpkgs#nixos-anywhere -- --flake .#cloud root@<your-server-ip>`
+    - Replace the output name if you've changed it
+    - The user doesn't have to be root but has to be able to `sudo` without entering a password
+    - You need Nix installed with the `nix-command` experimental feature enabled.
+      If this doesn't work for you on macOS, you can run this from a VM (preferably matching the server ISA).
+- If everything goes well, the server will reboot. Shortly after that you should be able to ssh into the server and get root access
+    - The server will also have a new SSH key, so you'll have to clear old records from `~/.ssh/known_hosts`
+
+### Adding basic configuration
+
+**Make sure you've removed the server's previous key from `~/.ssh/known_hosts` if you've connected to the server before!**
+
+Following successful installation, run `(cd postinstall && ./auto.sh <server_ip> <path_to_your_ssh_key>)` (once the server has rebooted). Or if you want to
+do this manually:
+- ssh into the server and run `nixos-generate-config`
+- replace `/etc/nixos/configuration.nix` with `postinstall/configuration.nix` from this repo
+- copy `postinstall/flake.nix` to `/etc/nixos/flake.nix`
+- `nixos-rebuild switch`
+
+### Next steps
+
+Configure your NixOS server as you want. The only things to keep in mind are:
+- there are no channels configured
+- it's using a flake for the system config and setting the nix path in `/etc/nixos/flake.nix`
+- the server's hostname is nixos
+
+You may want to change the hostname, pull in some flake with system config for that particular hostname, or you
+may want to just import some modules into your config.
+
+## Setting up a Laravel app
+
+After you have a NixOS server set up, you can use our `laravel.nix` module to start configuring Laravel sites.
+
+The module is fairly generic so it should work for most sites. It's written in a simple way, to be as easy to
+customize as possible if needed, while offering enough customization for most applications.
+
+Import the module in your system flake and invoke it with these parameters:
+```nix
+(laravelSite {
+  name = "mysite";
+  domain = "mysite.com";
+  phpPackage = pkgs.php84;
+
+  ssl = true; # optional, defaults to false
+  extraNginxConfig = "nginx configuration string"; # optional
+  sshKeys = [ "array" "of" "public" "ssh" "keys" ]; # optional
+  extraPackages = [ pkgs.nodejs_24 ]; # optional
+  queue = true; # start a queue worker - defaults to false, optional
+  queueArgs = "--tries=3"; # optional, default empty
+  generateSshKey = false; # optional, defaults to true
+  poolSettings = { # optional
+      "pm.max_children" = 12;
+      "php_admin_value[opcache_memory_consumption]" = "512";
+      "php_admin_flag[opcache.validate_timestamps]" = true;
+  };
+})
+```
+
+The module creates a new user (`laravel-${name}`), a `/srv/${name}` directory, configures
+cron to run every minute optionally starts a queue worker and configures php-fpm with
+good defaults (see below). The user has a home directory in `/home/laravel-${name}`
+(used mainly for `./cache` used by composer and npm) and the site is served from the srv
+directory.
+
+The default php-fpm opcache configuration is to cache everything *forever* without any
+revalidation. Therefore, make sure to include `sudo systemctl reload phpfpm-${name}` in
+your deployment script.
+
+To deploy your app, you can use ssh deployments, rather than webhooks triggering pull hooks
+or other techniques. Since this module creates a new user for each site, this deployment
+technique becomes non-problematic and it's one of the simplest things you can do. Just
+ssh-keygen a private key, make a GitHub Actions job use that on push, and include the
+public key in the site's `sshKeys` array. Then, to be able to `git pull` the site on the
+server, add the user's `~/.ssh/id_ed25519.pub` to the repository's deployment keys. The
+ssh key for the user is generated automatically (can be disabled by setting `generateSshKey`
+to false).
+
+Also, if you're using `ssl` you should put this line into your system config:
+```nix
+security.acme.email = "your@email.com";
+```
+
+A full system config can look something like this (excluding any additional configuration
+you may want to make):
+```nix
+{
+  description = "System flake";
+
+  inputs = {
+    nixpkgs.url = "github:nixos/nixpkgs?ref=nixos-unstable";
+  };
+
+  outputs = { self, nixpkgs, ... }@inputs: {
+    nixosConfigurations = let
+      system = "aarch64-linux";
+      pkgs = nixpkgs.legacyPackages.${system};
+      laravelSite = import ./laravel.nix;
+    in {
+      nixos = nixpkgs.lib.nixosSystem {
+        inherit system;
+
+        modules = [
+          { nix.nixPath = [ "nixpkgs=${inputs.nixpkgs}" ]; }
+          ./configuration.nix
+
+          # your (laravelSite { ... }) calls here
+        ];
+      };
+    };
+  };
+}
+```
+
+There's a million different ways to structure your system flake, so you may prefer to use
+something different. Note that `laravel.nix` is explicitly not a flake and not a top-level
+"input" - the goal is to just invoke it each time *to change system configuration*. We don't
+want an additional lockfile for the laravel module and we don't want to update the system
+lockfile whenever we make changes to the laravel module. With the most basic configuration,
+you should only have `nixpkgs` in your lockfile.
+
+There also isn't any special shell since Laravel is entirely handled by system daemons like
+nginx, php-fpm, cron, and optionally a queue worker systemd service. We do include a .bashrc
+with some echos to quickly remind you of the filesystem structure and available commands.
+
+Simply `scp laravel.nix root@<your server ip>:/etc/nixos/` and start writing config as above.