Add extraPoolSettings, add comments to parameters, README improvements

README.md

@@ -82,11 +82,15 @@ Import the module in your system flake and invoke it with these parameters:
   queue = true; # start a queue worker - defaults to false, optional
   queueArgs = "--tries=3"; # optional, default empty
   generateSshKey = false; # optional, defaults to true
-  poolSettings = { # optional
+  poolSettings = { # optional - overrides all of our defaults
     "pm.max_children" = 12;
     "php_admin_value[opcache_memory_consumption]" = "512";
     "php_admin_flag[opcache.validate_timestamps]" = true;
   };
+  # alternatively:
+  extraPoolSettings = { # merged with poolSettings, doesn't override our defaults
+    "pm.max_children" = 12;
+  }
 })
 ```
 
@@ -192,14 +196,14 @@ cloudflareOnly = true;
 in the site config. This will automatically add:
 ```nginx
 ssl_verify_client on;
-ssl_client_certificate <path to Cloudflare's default cert>;
+ssl_client_certificate "path to Cloudflare's default cert";
 ```
 
 Then just enable AOP in the `SSL/TLS -> Origin Server` setting of your CF zone.
 
 > The only caveat with using AOP is that you will not be able to access your app directly
 > *even from the same server* -- HTTP requests will be redirected to HTTPS and HTTPS will
-> fail due to a missing certificate. **But this isn't generally an issue in practice** since
+> fail due to a missing certificate. **But this is generally not an issue in practice** since
 > the server config we use doesn't use any special hosts records that'd try to bypass CF.
 > So running `curl https://your-app.com` on the server will work without issues. The only
 > thing that will NOT work is:
@@ -274,3 +278,28 @@ To check the up-to-date hashes, you can use:
 curl -s https://www.cloudflare.com/ips-v4 | sha256 | xargs nix hash convert --hash-algo sha256 --to nix32
 curl -s https://www.cloudflare.com/ips-v6 | sha256 | xargs nix hash convert --hash-algo sha256 --to nix32
 ```
+
+## Maintenance
+
+It's a good idea to have /etc/nixos tracked in version control so you can easily revert the config including
+the lockfile, not just system state.
+
+The only thing in your lockfile should be `nixpkgs` unless you add more things to your system config.
+
+After rebuilding the system several times, you will have some past generations and unused files in the Nix
+store that can be cleaned up.
+
+List past generations with:
+```sh
+sudo nix-env --list-generations --profile /nix/var/nix/profiles/system
+```
+
+Delete old ones:
+```sh
+sudo nix-env --delete-generations old --profile /nix/var/nix/profiles/system
+```
+
+Then clean garbage:
+```sh
+sudo nix-collect-garbage -d
+```

laravel.nix

@@ -1,4 +1,16 @@
-{ name, phpPackage, domains ? [], ssl ? false, cloudflareOnly ? false, extraNginxConfig ? null, sshKeys ? null, extraPackages ? [], queue ? false, queueArgs ? "", generateSshKey ? true, poolSettings ? {
+{
+  name, # Name of the site, the username and /srv/{name} will be based on this
+  phpPackage, # e.g. pkgs.php84
+  domains ? [], # e.g. [ "example.com" "acme.com" ]
+  ssl ? false, # Should SSL be used
+  cloudflareOnly ? false, # Should CF Authenticated Origin Pulls be used
+  extraNginxConfig ? null, # Extra nginx config string
+  sshKeys ? null, # SSH public keys used to log into the site's user for deployments
+  extraPackages ? [], # Any extra packages the user should have in $PATH
+  queue ? false, # Should a queue worker systemd service be created
+  queueArgs ? "", # Extra args for the queue worker (e.g. "--tries=2")
+  generateSshKey ? true, # Generate an SSH key for the user (used for GH deploy keys)
+  poolSettings ? { # PHP-FPM pool settings. Changing this will override all of these defaults
       "pm" = "dynamic";
       "pm.max_children" = 8;
       "pm.start_servers" = 2;
@@ -12,7 +24,10 @@
       "php_admin_value[opcache.revalidate_freq]" = "0";
       "php_admin_flag[opcache.validate_timestamps]" = false;
       "php_admin_flag[opcache.save_comments]" = true;
-}, ... }:
+  },
+  extraPoolSettings ? {}, # PHP-FPM pool settings merged into poolSettings. Doesn't override defaults
+  ...
+}:
 
 { config, lib, pkgs, ... }:
 let
@@ -157,7 +172,7 @@ in {
   services.phpfpm.pools.${name} = {
     user = mkUsername name;
     phpPackage = phpPackage;
-    settings = poolSettings // {
+    settings = poolSettings // extraPoolSettings // {
       "listen.owner" = config.services.nginx.user;
     };
   };