Replace caddy with nginx
Before this commit, we used Caddy. Here's what was needed to make that setup go:
- As we needed the layer4 plugin, we had to compile caddy with layer4 using an
unsupported technique in nix
- As the layer4 plugin did not support caddyfile, we had to use caddy.json
- We wrote some nix code to setup reverse proxy routes easily however this was
a challenge to reasonably maintain, and caddy.json is far
less-well-documented than caddyfile leading to a significant amount of pain
if we ever needed to break out
- Several modules in NixOS use nginx by default (privatebin, nextcloud etc.), we
need to disable and then replicate their setup. This is often nontrivial
Nginx has some distinct advantages for Clicks specifically on NixOS:
- "Streams" are supported Out-Of-The box, meaning no layer4 plugin
- Nginx has a standard nixified interface for virtual hosts, meaning there's no
breaking out into nginx config for http
- Note how you may still have to break out for TCP/UDP streams
- Nginx configurations, including relatively complex ones (e.g. nextcloud) are
often included with modules by default. Choosing nginx will avoid us rewriting
these, as well as all the pain and debugging that comes with that
Additionally:
- Nginx has excellent integration with the builtin ACME module. I am satisfied
with its ability to replace caddy on that front
- A major point in the favor of caddy is usability. Unfortunately, this really
only seems to apply to caddyfile with caddy.json being significantly more
cumbersome to write, even with nix helper functions
- It is trivial to write some simple but decent helper functions for nginx
Alternatives considered:
- Stick with caddy
- Too much maintenance burden
- We struggle to update it frequently, due to the plugin install bits
- Use traefik
- From a short look, it's too complex for our needs
- It doesn't have configs built into nix in the same way as nginx
- Use apache2
- Apache has no analogue to nginx streams
- It doesn't have configs built into nix in the same way as nginx
This commit will need a followup in future to improve the typing of the Service
type. We have a very basic implementation but it would be nice to be able to
check for types that are inside it rather than just the top level.
Change-Id: I25e7ba48cec6b9308e6aa9a14f57a8c192918c92
diff --git a/modules/nginx.nix b/modules/nginx.nix
new file mode 100644
index 0000000..64ad1ce
--- /dev/null
+++ b/modules/nginx.nix
@@ -0,0 +1,187 @@
+{ config, lib, pkgs, helpers, base, ... }:
+lib.recursiveUpdate
+{
+ options.clicks = {
+ nginx = {
+ services = lib.mkOption {
+ type = with lib.types;
+ listOf (submodule {
+ options = {
+ host = lib.mkOption { type = str; };
+ extraHosts = lib.mkOption { type = listOf str; };
+ secure = lib.mkOption { type = bool; };
+ service = lib.mkOption {
+ type = let
+ validServiceTypes = {
+ "redirect" = {
+ to = ["string" str];
+ permanent = ["bool" bool];
+ };
+ "reverseproxy" = {
+ to = ["string" str];
+ };
+ "php" = {
+ root = ["string" str];
+ socket = ["string" str];
+ };
+ "directory" = {
+ private = ["bool" bool];
+ root = ["string" str];
+ };
+ "file" = {
+ path = ["string" str];
+ };
+ "path" = {
+ path = ["string" str];
+ service = ["set" serviceType];
+ };
+ "compose" = {
+ services = ["list" (listOf serviceType)];
+ };
+ "status" = {
+ statusCode = ["int" int];
+ };
+ };
+
+ serviceType = mkOptionType {
+ name = "Service";
+
+ description = "clicks Nginx service";
+ descriptionClass = "noun";
+
+ check = (x:
+ if (builtins.typeOf x) != "set"
+ then lib.warn "clicks nginx services must be sets but ${x} is not a set" false
+ else if !(builtins.hasAttr "type" x)
+ then lib.warn "clicks nginx services must have a type attribute but ${x} does not" false
+ else if !(builtins.hasAttr x.type validServiceTypes)
+ then lib.warn "clicks nginx services must have a valid type, but ${x.type} is not one" false
+ else (let
+ optionTypes =
+ (builtins.mapAttrs (n: o: builtins.elemAt o 0) validServiceTypes.${x.type})
+ // { type = "string"; };
+ in (lib.pipe x [
+ (builtins.mapAttrs (n: o: (builtins.hasAttr n optionTypes) && optionTypes.${n} == (builtins.typeOf o)))
+ lib.attrValues
+ (builtins.all (x: x))
+ ]) && (lib.pipe optionTypes [
+ (builtins.mapAttrs (n: _: builtins.hasAttr n x))
+ lib.attrValues
+ (builtins.all (x: x))
+ ] )));
+ };
+ in serviceType;
+ };
+ type = lib.mkOption { type = strMatching "hosts"; };
+ };
+ });
+ example = lib.literalExpression ''
+ with helpers.nginx; [
+ (Host "example.clicks.codes" (ReverseProxy "generic:1001"))
+ ]'';
+ description = lib.mdDoc ''
+ Connects hostnames to services for your nginx server. We recommend using the Clicks helper to generate these
+ '';
+ default = [ ];
+ };
+ serviceAliases = lib.mkOption {
+ type = with lib.types;
+ listOf (submodule {
+ options = {
+ host = lib.mkOption {
+ type = str;
+ example = "example.clicks.codes";
+ description = ''
+ The ServerName of the server. If you override this in the nginx server block, you still need to put in the name of the attribute
+ '';
+ };
+ aliases = lib.mkOption {
+ type = listOf str;
+ example = [ "example2.clicks.codes" "example.coded.codes" ];
+ description = ''
+ A list of servers to add as aliases
+ '';
+ };
+ type = lib.mkOption { type = strMatching "aliases"; };
+ };
+ });
+ example = lib.literalExpression ''
+ with helpers.nginx; [
+ (Host "example.clicks.codes" (ReverseProxy "generic:1001"))
+ ]'';
+ description = lib.mdDoc ''
+ Adds additional host names to your nginx server. If you're using `clicks.nginx.services`
+ you should generally use a Hosts block instead
+ '';
+ default = [ ];
+ };
+ streams = lib.mkOption {
+ type = with lib.types; listOf (submodule {
+ options = {
+ internal = lib.mkOption { type = str; };
+ external = lib.mkOption { type = port; };
+ protocol = lib.mkOption { type = strMatching "^(tcp|udp)$"; };
+ };
+ });
+ example = lib.literalExpression ''
+ with helpers.nginx; [
+ (Stream 1001 "generic:1002" "tcp")
+ ]'';
+ description = lib.mdDoc ''
+ A list of servers to be placed in the nginx streams block. We recommend using the Clicks helper to generate these
+ '';
+ default = [ ];
+ };
+ };
+ };
+ config = {
+ services.nginx = {
+ enable = true;
+ enableReload = true;
+
+ virtualHosts = lib.recursiveUpdate (helpers.nginx.Merge
+ config.clicks.nginx.services) # clicks.nginx.services
+ (lib.pipe config.clicks.nginx.serviceAliases [
+ (map (alias: {
+ name = alias.host;
+ value.serverAliases = alias.aliases;
+ }))
+ builtins.listToAttrs
+ ]); # clicks.nginx.serviceAliases
+
+ streamConfig = builtins.concatStringsSep "\n" (map (stream: ''
+ server {
+ listen ${builtins.toString stream.external}${lib.optionalString (stream.protocol == "udp") " udp"};
+ proxy_pass ${builtins.toString stream.internal};
+ }
+ '') config.clicks.nginx.streams);
+ };
+
+ networking.firewall.allowedTCPPorts = lib.pipe config.clicks.nginx.streams [
+ (builtins.filter (stream: stream.protocol == "tcp"))
+ (map (stream: stream.external))
+ ];
+ networking.firewall.allowedUDPPorts = lib.pipe config.clicks.nginx.streams [
+ (builtins.filter (stream: stream.protocol == "udp"))
+ (map (stream: stream.external))
+ ];
+
+ security.acme.defaults = {
+ email = "admin@clicks.codes";
+ credentialsFile = config.sops.secrets.cloudflare_cert__api_token.path;
+ };
+ security.acme.acceptTerms = true;
+
+ sops.secrets.cloudflare_cert__api_token = {
+ mode = "0660";
+ owner = config.users.users.nginx.name;
+ group = config.users.users.acme.group;
+ sopsFile = ../secrets/cloudflare-cert.env.bin;
+ format = "binary";
+ };
+ };
+} (
+ if base != null
+ then {
+ config.security.acme.certs = builtins.mapAttrs (_: v: { webroot = null; dnsProvider = "cloudflare"; }) base.config.security.acme.certs;
+ } else {})