dunkirk.sh

Kieran’s opinionated NixOS infrastructure. Declarative server config, self-hosted services, automated deployments.

For machine inventory, apply commands, repo layout, and conventions see AGENTS.md.

• Installation — getting started on macOS, NixOS, or home-manager
• Deployment — CI/CD workflows for infrastructure and application code
• Services — architecture overview and service documentation
• Secrets — agenix workflow
• mkService — the service factory reference
• Modules — custom NixOS and home-manager modules

Live status at infra.dunkirk.sh. Machine manifest: nix eval --json .#services-manifest.

Installation

Warning: This configuration will not work without changing the secrets since they are encrypted with agenix.

macOS with nix-darwin

1. Install Nix:

curl -fsSL https://install.determinate.systems/nix | sh -s -- install

2. Clone and apply:

git clone git@github.com:taciturnaxolotl/dots.git
cd dots
darwin-rebuild switch --flake .#atalanta

Home Manager

Install Nix, copy SSH keys, then:

curl -fsSL https://install.determinate.systems/nix | sh -s -- install --determinate
git clone git@github.com:taciturnaxolotl/dots.git
cd dots
nix-shell -p home-manager
home-manager switch --flake .#nest

Set up atuin for shell history sync:

atuin login
atuin import

NixOS

Using nixos-anywhere (recommended for remote)

Only works with prattle and terebithia which have disko configs.

nix run github:nix-community/nixos-anywhere -- \
  --flake .#prattle \
  --generate-hardware-config nixos-facter ./machines/prattle/facter.json \
  --build-on-remote \
  root@<ip-address>

Using the install script

curl -L https://raw.githubusercontent.com/taciturnaxolotl/dots/main/install.sh -o install.sh
chmod +x install.sh
./install.sh

Post-install

After first boot, log in with user kierank and the default password, then:

passwd kierank
sudo mv /etc/nixos ~/dots
sudo ln -s ~/dots /etc/nixos
sudo chown -R $(id -un):users ~/dots
atuin login && atuin sync

Deployment

Two deploy paths: infrastructure (NixOS config changes) and application code (per-service repos).

Infrastructure

Pushing to main triggers .github/workflows/deploy.yaml which runs deploy-rs over Tailscale to rebuild NixOS on the target machine.

# From the dev shell (preferred)
nix develop
deploy .#terebithia
deploy .#prattle

# Manual one-off
nix run 'github:serokell/deploy-rs' -- --remote-build --ssh-user kierank .#terebithia

Builds happen on the target machine (--remote-build), so CI only needs Nix and network access.

Application Code

Each service repo has a minimal workflow calling the reusable .github/workflows/deploy-service.yml. On push to main:

1. Connects to Tailscale (tag:deploy)
2. SSHes as the service user (e.g., cachet@terebithia) via Tailscale SSH
3. Snapshots the SQLite DB (if db_path is provided)
4. git pull + bun install --frozen-lockfile + sudo systemctl restart
5. Health check (HTTP URL or systemd status fallback)
6. Auto-rollback on failure (restores DB snapshot + reverts to previous commit)

Per-app workflow. Copy and change the with: values:

name: Deploy
on:
  push:
    branches: [main]
  workflow_dispatch:
jobs:
  deploy:
    uses: taciturnaxolotl/dots/.github/workflows/deploy-service.yml@main
    with:
      service: cachet
      health_url: https://cachet.dunkirk.sh/health
      db_path: /var/lib/cachet/data/cachet.db
    secrets:
      TS_OAUTH_CLIENT_ID: ${{ secrets.TS_OAUTH_CLIENT_ID }}
      TS_OAUTH_SECRET: ${{ secrets.TS_OAUTH_SECRET }}

Omit health_url to fall back to systemctl is-active. Omit db_path for stateless services.

Adding a new service

1. Create a module in modules/nixos/services/ using mkService or a custom module
2. Register secrets in secrets/secrets.nix and encrypt with agenix
3. Enable in the target machine’s default.nix
4. Add a deploy workflow to the app repo (if it has one)

See modules/nixos/services/cachet.nix for a minimal mkService example.

Services

All services run behind Caddy with Cloudflare DNS TLS. Most use the mkService factory which provides systemd units, dedicated users, reverse proxy, backup integration, and port conflict detection.

Live status

• Dashboard: infra.dunkirk.sh
• Machine manifest: nix eval --json .#services-manifest or /services.json

Service documentation

These services have detailed option references and architecture notes:

• bore — HTTP/TCP/UDP tunnel proxy with optional OAuth
• cedarlogic — circuit simulator with WebSocket collaboration
• control — admin dashboard for Caddy feature toggles
• emojibot — multi-instance Slack emoji management
• herald — git SSH hosting with email via SMTP/DKIM
• knot-sync — mirrors Tangled knot repos to GitHub on cron

For all other services, check the manifest or the module source in modules/nixos/services/.

bore (server)

Lightweight tunneling server built on frp. Supports HTTP (wildcard subdomains), TCP, and UDP tunnels with optional OAuth authentication via Indiko.

Domain: bore.dunkirk.sh · frp port: 7000

This is a custom module — it does not use mkService.

Options

Authentication

When enabled, all HTTP tunnels are gated behind Indiko OAuth. Users must sign in before accessing tunneled services.

After authentication, these headers are passed to tunneled services:

• X-Auth-User — user’s profile URL
• X-Auth-Name — display name
• X-Auth-Email — email address

See bore (client) for the home-manager client module.

cedarlogic

Browser-based circuit simulator with real-time collaboration via WebSockets.

Domain: cedarlogic.dunkirk.sh · Port: 3100 · Runtime: custom

Extra options

Caddy routing

Cedarlogic disables the default mkService Caddy config and uses path-based routing to three backends:

Build step

On initial scaffold, cedarlogic installs deps and builds:

bun install → parse-gates → bun run build (Vite)

Subsequent deploys handle their own build via the deploy workflow. The build has a 120s timeout to accommodate Vite compilation.

control

Admin dashboard for Caddy feature toggles. Provides a web UI to enable/disable paths on other services (e.g. blocking player tracking on the map).

Domain: control.dunkirk.sh · Port: 3010 · Runtime: bun

Extra options

flags

Defines per-domain feature flags that control blocks paths and redacts JSON fields.

atelier.services.control.flags."map.dunkirk.sh" = {
  name = "Map";
  flags = {
    "block-tracking" = {
      name = "Block Player Tracking";
      description = "Disable real-time player location updates";
      paths = [
        "/sse"
        "/sse/*"
        "/tiles/*/markers/pl3xmap_players.json"
      ];
      redact."/tiles/settings.json" = [ "players" ];
    };
  };
};

The flags config is serialized to flags.json and passed to control via the FLAGS_CONFIG environment variable.

emojibot

Slack emoji management service. Supports multiple instances for different workspaces.

Runtime: bun · Stateless (no database)

This is a custom module — it does not use mkService. Each instance gets its own systemd service, user, and Caddy virtual host.

Instance options

Instances are defined under atelier.services.emojibot.instances.<name>:

atelier.services.emojibot.instances = {
  hackclub = {
    enable = true;
    domain = "hc.emojibot.dunkirk.sh";
    port = 3002;
    workspace = "hackclub";
    channel = "C02T3CU03T3";
    repository = "https://github.com/taciturnaxolotl/emojibot";
    secretsFile = config.age.secrets."emojibot/hackclub".path;
    healthUrl = "https://hc.emojibot.dunkirk.sh/health";
  };
};

Current instances

herald

Git SSH hosting with email notifications. Provides a git push interface over SSH and sends email via SMTP/DKIM.

Domain: herald.dunkirk.sh · SSH Port: 2223 · HTTP Port: 8085

This is a custom module — it does not use mkService.

Options

SMTP

DKIM

knot-sync

Mirrors Tangled knot repositories to GitHub on a cron schedule.

This is a custom module — it does not use mkService. Runs as a systemd timer, not a long-running service.

Options

Secrets

Secrets are managed using agenix — encrypted at rest in the repo and decrypted at activation time to /run/agenix/.

Usage

Create or edit a secret:

cd secrets && agenix -e myapp.age

The secret file contains environment variables, one per line:

DATABASE_URL=postgres://...
API_KEY=xxxxx
SECRET_TOKEN=yyyyy

Adding a new secret

1. Add the public key entry to secrets/secrets.nix:

"service-name.age".publicKeys = [ kierank ];

2. Create and encrypt the secret:

agenix -e secrets/service-name.age

3. Declare in machine config:

age.secrets.service-name = {
  file = ../../secrets/service-name.age;
  owner = "service-name";
};

4. Reference as config.age.secrets.service-name.path in the service module.

Identity paths

The decryption keys are SSH keys configured per machine:

age.identityPaths = [
  "/home/kierank/.ssh/id_rsa"
  "/etc/ssh/id_rsa"
];

Modules

Custom NixOS and home-manager modules under the atelier.* namespace. These wrap and extend upstream packages with opinionated defaults and structured configuration.

All modules live under modules/nixos/ and modules/home/. Machines using import-tree automatically discover every .nix file in those trees. Modules only activate when their enable option is set to true.

Documented modules

These have detailed option references and examples:

NixOS

• tuigreet — login greeter (atelier.apps.tuigreet)
• wifi — declarative Wi-Fi profiles with eduroam (atelier.network.wifi)

Home-manager

• shell — zsh + oh-my-posh + Tangled tooling (atelier.shell)
• ssh — SSH config with zmx persistent sessions (atelier.ssh)
• helix — evil-helix with LSPs, wakatime, harper (atelier.apps.helix)
• bore (client) — tunnel client CLI (atelier.bore)
• pbnj — pastebin CLI (atelier.pbnj)
• wut — git worktree manager (atelier.shell.wut)

Other modules

Many more modules exist without dedicated doc pages. Browse the source:

• modules/home/apps/ — ghostty, alacritty, git, jj, qutebrowser, spotify, halloy, irssi, tofi
• modules/home/aesthetics/ — theming (Catppuccin), wallpapers
• modules/home/wm/ — hyprland, yabai/skhd
• modules/nixos/system/ — authentication, machine metadata
• modules/nixos/services/ — 20+ service modules (see Services)

tuigreet

Configures greetd with tuigreet as the login greeter. Exposes nearly every tuigreet CLI flag as a typed Nix option.

Options

All options under atelier.apps.tuigreet:

Core

Display

Layout

Session management

User menu

Power commands

Keybindings

wifi

Declarative Wi-Fi profile manager using NetworkManager. Supports three ways to supply passwords and has built-in eduroam (WPA-EAP) support.

Options

All options under atelier.network.wifi:

Profiles

Defined under atelier.network.wifi.profiles.<ssid>:

Only one of psk, pskVar, or pskFile should be set per profile.

Example

atelier.network.wifi = {
  enable = true;
  hostName = "moonlark";
  nameservers = [ "1.1.1.1" "8.8.8.8" ];
  envFile = config.age.secrets.wifi.path;

  profiles = {
    "Home Network" = {
      pskVar = "HOME_PSK";  # read from envFile
    };
    "eduroam" = {
      eduroam = true;
      identity = "user@university.edu";
      pskVar = "EDUROAM_PSK";
    };
    "Phone Hotspot" = {
      pskFile = config.age.secrets.hotspot.path;
    };
  };
};

shell

Zsh configuration with oh-my-posh prompt, syntax highlighting, fzf-tab, zoxide, and Tangled git workflow tooling.

Options

All options under atelier.shell:

Tangled

Options for the tangled-setup and mkdev scripts that manage dual-remote git workflows (Tangled knot + GitHub).

Included tools

• tangled-setup — configures a repo with origin pointing to knot and github pointing to GitHub
• mkdev — creates a new repo on both Tangled and GitHub simultaneously
• oh-my-posh — custom prompt showing path, git status (ahead/behind), exec time, nix-shell indicator, ZMX session, SSH hostname
• Aliases — cat=bat, ls=eza, cd=z (zoxide), and more

ssh

Declarative SSH config with per-host options and zmx (persistent tmux-like sessions over SSH) integration.

Options

All options under atelier.ssh:

zmx

When zmx is enabled for a host, the SSH config injects RemoteCommand, RequestTTY force, and ControlMaster/ControlPersist settings. Shell aliases are also added: zmls, zmk, zma, ash.

Hosts

Per-host config under atelier.ssh.hosts.<name>:

Example

atelier.ssh = {
  enable = true;
  zmx.enable = true;
  zmx.hosts = [ "terebithia" "ember" ];

  hosts = {
    terebithia = {
      hostname = "terebithia";
      user = "kierank";
      forwardAgent = true;
      zmx = true;
    };
    "github.com" = {
      identityFile = "~/.ssh/id_rsa";
    };
  };
};

helix

Evil-helix (vim-mode fork) with comprehensive LSP setup, wakatime tracking on every language, and harper grammar checking.

Options

All options under atelier.apps.helix:

Language servers

The module configures 15+ language servers out of the box:

All languages also get:

• wakatime-ls — coding time tracking
• harper-ls — grammar and spell checking

Note: After install, run hx -g fetch && hx -g build to compile tree-sitter grammars.

bore (client)

Interactive CLI for creating tunnels to the bore server. Built with gum, supports HTTP, TCP, and UDP tunnels.

Options

All options under atelier.bore:

Usage

bore                  # Interactive menu
bore myapp 3000       # Quick HTTP tunnel: myapp.bore.dunkirk.sh → localhost:3000
bore myapp 3000 --auth  # With OAuth authentication
bore myapp 3000 --save  # Save to bore.toml for reuse

Tunnels can also be defined in a bore.toml:

[myapp]
port = 3000
auth = true
labels = ["dev"]

pbnj

Pastebin CLI with automatic language detection, clipboard integration, and agenix auth.

Options

All options under atelier.pbnj:

Usage

pbnj                          # Interactive menu
pbnj upload myfile.py         # Upload file (auto-detects Python)
cat output.log | pbnj upload  # Upload from stdin
pbnj list                     # List pastes
pbnj delete <id>              # Delete a paste

Supports 25+ languages via file extension detection. Automatically copies the URL to clipboard (wl-copy/xclip/pbcopy depending on platform).

wut

Worktrees Unexpectedly Tolerable — a git worktree manager that keeps worktrees organized under .worktrees/.

Options

Usage

wut new feat/my-feature   # Create worktree + branch under .worktrees/
wut list                   # Show all worktrees
wut go feat/my-feature     # cd into worktree (via shell wrapper)
wut go                     # Interactive picker
wut path feat/my-feature   # Print worktree path
wut rm feat/my-feature     # Remove worktree + delete branch

Shell integration

Wut needs to cd the calling shell, which a subprocess can’t do directly. It works by printing a __WUT_CD__=/path marker that a zsh wrapper function intercepts:

wut() {
  output=$(/path/to/wut "$@")
  if [[ "$output" == *"__WUT_CD__="* ]]; then
    cd "${output##*__WUT_CD__=}"
  else
    echo "$output"
  fi
}

This wrapper is automatically injected into initContent when the module is enabled.

Safety

• wut rm refuses to delete worktrees with uncommitted changes (use --force to override)
• wut rm warns before deleting unmerged branches
• The main/master branch worktree cannot be removed

mkService

modules/lib/mkService.nix is the service factory used by most atelier services. It takes a set of parameters and returns a NixOS module with standardized options, systemd service, Caddy reverse proxy, and backup integration.

Factory parameters

Options

Every mkService module creates options under atelier.services.<name>:

Core

Data declarations

Used by the backup system to automatically discover what to back up.

Caddy

What it sets up

• System user and group — dedicated user in the services group with sudo for systemctl restart/stop/start/status
• Systemd service — ExecStartPre creates dirs as root, preStart clones repo and installs deps, ExecStart runs the application
• Caddy virtual host — TLS via Cloudflare DNS challenge, reverse proxy to localhost port
• Port conflict detection — assertions prevent two services from binding the same port
• Security hardening — NoNewPrivileges, ProtectSystem=strict, ProtectHome, PrivateTmp

Example

Minimal service module:

let
  mkService = import ../../lib/mkService.nix;
in
mkService {
  name = "myapp";
  description = "My application";
  defaultPort = 3000;
  runtime = "bun";
  entryPoint = "src/index.ts";

  extraConfig = cfg: {
    systemd.services.myapp.serviceConfig.Environment = [
      "DATABASE_PATH=${cfg.dataDir}/data/app.db"
    ];

    atelier.services.myapp.data = {
      sqlite = "${cfg.dataDir}/data/app.db";
    };
  };
}

Then enable in the machine config:

atelier.services.myapp = {
  enable = true;
  domain = "myapp.dunkirk.sh";
  repository = "https://github.com/taciturnaxolotl/myapp";
  secretsFile = config.age.secrets.myapp.path;
  healthUrl = "https://myapp.dunkirk.sh/health";
};

Service utility functions

Service utility functions for the atelier infrastructure.

These functions operate on NixOS configurations to extract service metadata for dashboards, monitoring, and documentation.

services.isMkService

Check whether an atelier service config value has the standard mkService shape (has enable, domain, port, _description).

Arguments

• cfg — an attribute set from config.atelier.services.<name>

Type

AttrSet -> Bool

Example

isMkService config.atelier.services.cachet
=> true

services.mkServiceEntry

Convert a single mkService config into a manifest entry.

Arguments

• name — the service name (attribute key)
• cfg — the service config attrset

Type

String -> AttrSet -> AttrSet

Example

mkServiceEntry "cachet" config.atelier.services.cachet
=> { name = "cachet"; domain = "cachet.dunkirk.sh"; ... }

services.mkManifest

Build a services manifest from an evaluated NixOS config.

Discovers all enabled mkService-based services plus emojibot instances. Returns a sorted list of service entries suitable for JSON serialisation.

Arguments

• config — the fully evaluated NixOS configuration

Type

AttrSet -> [ AttrSet ]

Example

mkManifest config
=> [ { name = "cachet"; domain = "cachet.dunkirk.sh"; ... } ... ]

services.mkMachinesManifest

Build a manifest of all machines and their services.

Takes one or more attrsets of system configurations (NixOS, Darwin, or home-manager) and returns an attrset keyed by machine name. Only machines with atelier.machine.enable = true are included.

Arguments

• configSets — list of attrsets of system configurations

Type

[ AttrSet ] -> AttrSet

Example

mkMachinesManifest [ self.nixosConfigurations self.darwinConfigurations ]
=> { terebithia = { hostname = "terebithia"; services = [ ... ]; }; }