A small reverse proxy for a Nix-managed homelab, in the spirit of Caddy but with the scope of one household: hostname routing to HTTP backends, static files, TLS from certificates on disk, SNI passthrough from a public edge host over an overlay network, an HTTP-to-HTTPS redirect for port 80, and a NixOS module that generates all of its configuration.
Status: v0.1 done; v0.2 (SIGHUP reload, sd_notify, NixOS module) implemented,
awaiting deployment; v0.3 (static routes) implemented; v1.0 (SNI passthrough,
PROXY protocol) passed and deployed; v1.1 (port 80 redirect) implemented, VM test pending on builder. Decisions live in docs/adr/,
the plan in docs/milestones.md, the config reference in docs/config.md.
- One binary, two roles (ADR 0001): TLS-terminating proxy in the homelab, SNI/port passthrough on the public edge. Private keys never leave the homelab.
- Fully declarative (ADR 0002): an explicit TOML file generated by the NixOS module, reloaded on SIGHUP (ADR 0003). Secrets are file paths, never values.
- Certificates are files on disk issued by hanko (ADR 0004); genkan runs no ACME challenge of any kind.
- Standard library first (ADR 0005).
Nix flake: package, nixosModules.default, devShell, checks. nix flake check runs go vet and the unit tests, and on Linux builds the validated
config of nix/example.nix, checks that a typo in it
fails the build, and runs the NixOS VM tests of
nix/vm-test.nix and nix/vm-test-edge.nix
(Linux builder only: Forgejo CI); nix develop gives go and gopls; nix fmt formats the
Nix files.
services.genkan = {
enable = true;
listeners.lan.address = "[fd42::10]:443"; # default: one listener on ":443"
certificates.home = { # files written by hanko, or sops paths
hosts = [ "*.home.example.org" ];
cert = "/var/lib/hanko/home/fullchain.pem";
key = "/var/lib/hanko/home/key.pem";
};
sites."git.home.example.org".backend = "http://127.0.0.1:3000";
sites."site.home.example.org".root = pkgs.my-site; # static files, or a path such as "/var/www/site"
};Each site takes the certificate whose hosts contain its name, exact before
wildcard, unless it sets certificate. settings is the raw TOML of
docs/config.md; definitions there add to the generated
ones. A config change reloads genkan.service instead of restarting it, and so
does hanko after writing a certificate (genkan re-reads the files on SIGHUP and
never watches them). The service reads hanko's files through its own group: hanko's
per-certificate group must be genkan. No security.acme, no state
directory.
The two v1.0 roles (ADR 0002):
# Edge: public HTTPS by SNI, raw, with the client address in a PROXY v2 header; git SSH by port.
services.genkan = {
enable = true;
listeners.public-https.address = ":443";
listeners.public-ssh.address = ":2222";
passthrough.homelab-https = {
listener = "public-https";
sni = [ "git.example.org" ];
backend = "[fd42::10]:8443";
sendProxy = true;
};
passthrough.git-ssh = { listener = "public-ssh"; backend = "[fd42::10]:2222"; }; # no sni: tcp listener
httpRedirect.enable = true; # v1.1: ":80" answers 301 to https://, same host and path
};
# Homelab: the overlay listener fed by the edge. Sites are served there only when they name it.
services.genkan = {
listeners.lan.address = "[fd42::10]:443";
listeners.edge = {
address = "[fd42::10]:8443";
acceptProxy = true;
trustedSources = [ "fd42::1/128" ];
};
sites."git.example.org" = { backend = "http://127.0.0.1:3000"; listeners = [ "lan" "edge" ]; };
};Apache-2.0.