flynn/docs/plans/2026-02-16-deployment-targets.md

Milestone 6 (P3): Deployment Targets (Nix + Fly/Railway/Render)

Date: 2026-02-16

Goals

• Provide a Nix flake/package that builds dist/ and preserves dist/gateway/ui adjacency.
• Provide an optional NixOS module for running Flynn as a systemd service.
• Add first-class docs and templates for Fly.io / Railway / Render.
• Ensure PaaS network binding works (server.localhost: false) and port binding works (PORT env override).

Implementation

Nix

• Added flake.nix with:
  • packages.flynn / packages.default
  • apps.default (nix run)
  • devShells.default (nix develop)
  • overlays.default (exposes pkgs.flynn)
  • nixosModules.flynn
• Added Nix package definition: nix/package.nix (builds via pnpm build).
• Added NixOS module: nix/module.nix (services.flynn.*).
• Added docs: docs/deployment/NIX.md.

PaaS

• Added a PaaS-friendly config template: config/paas.yaml (server.localhost: false).
• Updated Dockerfile to ship a default config at /config/config.yaml so the image is runnable without a bind-mount.
• Added templates:
  • Fly.io: deploy/flyio/fly.toml
  • Railway: deploy/railway/railway.toml
  • Render: deploy/render/render.yaml
• Added docs: docs/deployment/PAAS.md.

Acceptance Notes

• pnpm build still copies gateway UI to dist/gateway/ui (required adjacency).
• PORT env override is implemented in src/config/loader.ts (completed earlier on 2026-02-16).
• For PaaS/container routing, use server.localhost: false (baked into config/paas.yaml).