Skip to content
scorsiPublic

About

玄関 — my Caddy-like reverse proxy in Go: TLS, routing and the front door of my homelab (mirror of my Forgejo)

Resources

Stars

0 stars

Watchers

0 watching

Forks

Latest commit

 

History

44 Commits

Folders and files

Repository files navigation

genkan (玄関)

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.

Shape

  • 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).

Building

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.

NixOS module

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" ]; };
};

License

Apache-2.0.

About

玄関 — my Caddy-like reverse proxy in Go: TLS, routing and the front door of my homelab (mirror of my Forgejo)

Resources

Stars

0 stars

Watchers

0 watching

Forks

Contributors

Languages