dunkirk.sh

Kieran's opinionated NixOS infrastructure — declarative server config, self-hosted services, and automated deployments.

Layout

~/dots
├── .github/workflows  # CI/CD (deploy-rs + per-service reusable workflow)
├── dots               # config files symlinked by home-manager
│   └── wallpapers
├── machines
│   ├── atalanta       # macOS M4 (nix-darwin)
│   ├── ember          # dell r210 server (basement)
│   ├── moonlark       # framework 13 (dead)
│   ├── nest           # shared tilde server (home-manager only)
│   ├── prattle        # oracle cloud x86_64
│   ├── tacyon         # rpi 5
│   └── terebithia     # oracle cloud aarch64 (main server)
├── modules
│   ├── lib
│   │   └── mkService.nix  # service factory (see Deployment section)
│   ├── home           # home-manager modules
│   │   ├── aesthetics # theming and wallpapers
│   │   ├── apps       # app configs (ghostty, helix, git, ssh, etc.)
│   │   ├── system     # shell, environment
│   │   └── wm/hyprland
│   └── nixos          # nixos modules
│       ├── apps       # system-level app configs
│       ├── services   # self-hosted services (mkService-based + custom)
│       │   ├── restic # backup system with CLI
│       │   └── bore   # tunnel proxy
│       └── system     # pam, wifi
├── packages           # custom nix packages
└── secrets            # agenix-encrypted secrets

Machines

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.

# manual deploy
nix run 'github:serokell/deploy-rs' -- --remote-build --ssh-user kierank .

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.

mkService

modules/lib/mkService.nix standardizes service modules. A call to mkService { ... } provides:

• Systemd service with initial git clone (subsequent deploys via GitHub Actions)
• Caddy reverse proxy with TLS via Cloudflare DNS and optional rate limiting
• Data declarations (sqlite, postgres, files) that feed into automatic backups
• Dedicated system user with sudo for restart/stop/start (enables per-user Tailscale ACLs)
• Port conflict detection, security hardening, agenix secrets

Adding a new service

1. Create a module in modules/nixos/services/
2. Enable it in machines/terebithia/default.nix
3. Add a deploy workflow to the app repo

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

Machine health checks

Machines with Tailscale enabled automatically expose their hostname for reachability checks in the services manifest via atelier.machine.tailscaleHost. This defaults to networking.hostName when services.tailscale.enable is true.

Services

Services are grouped by machine in the services manifest. Machines with Tailscale enabled automatically expose their hostname for reachability checks via atelier.machine.tailscaleHost.

Machines

terebithia

All services run behind Caddy with Cloudflare DNS TLS.

mkService-based

Multi-instance

Custom / external

Services manifest

The manifest is now grouped by machine. Evaluate with:

nix eval --json .#services-manifest

Output shape:

{
  "terebithia": {
    "hostname": "terebithia",
    "tailscale_host": "terebithia",
    "services": [{ "name": "cachet", "health_url": "https://cachet.dunkirk.sh/health", ... }]
  }
}

Architecture

Each mkService module provides:

• Systemd service — initial git clone for scaffolding, subsequent deploys via GitHub Actions
• Caddy reverse proxy — TLS via Cloudflare DNS challenge, optional rate limiting
• Data declarations — sqlite, postgres, files feed into automatic backups
• Dedicated user — sudo for restart/stop/start, per-user Tailscale SSH ACLs
• Port conflict detection — assertions prevent two services binding the same port

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.

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.

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

battleship-arena

Battleship game server with web interface and SSH-based bot submission.

Domain: battleship.dunkirk.sh · Web Port: 8081 · SSH Port: 2222

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

Options

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.

Backups

Services are automatically backed up nightly using restic to Backblaze B2. Backup targets are auto-discovered from data.sqlite/data.postgres/data.files declarations in mkService modules.

Schedule

• Time: 02:00 AM daily
• Random delay: 0–2 hours (spreads load across services)
• Retention: 3 snapshots, 7 daily, 5 weekly, 12 monthly

CLI

The atelier-backup command provides an interactive TUI:

sudo atelier-backup              # Interactive menu
sudo atelier-backup status       # Show backup status for all services
sudo atelier-backup list         # Browse snapshots
sudo atelier-backup backup       # Trigger manual backup
sudo atelier-backup restore      # Interactive restore wizard
sudo atelier-backup dr           # Disaster recovery mode

Service integration

Automatic (mkService)

Services using mkService with data.* declarations get automatic backup:

mkService {
  name = "myapp";
  extraConfig = cfg: {
    atelier.services.myapp.data = {
      sqlite = "${cfg.dataDir}/data/app.db";  # Auto WAL checkpoint + stop/start
      files = [ "${cfg.dataDir}/uploads" ];    # Just backed up, no hooks
    };
  };
}

The backup system automatically checkpoints SQLite WAL, stops the service during backup, and restarts after completion.

Manual registration

For services not using mkService:

atelier.backup.services.myservice = {
  paths = [ "/var/lib/myservice" ];
  exclude = [ "*.log" "cache/*" ];
  preBackup = "systemctl stop myservice";
  postBackup = "systemctl start myservice";
};

Disaster recovery

On a fresh NixOS install:

1. Rebuild from flake: nixos-rebuild switch --flake .#hostname
2. Run: sudo atelier-backup dr
3. All services restored from latest snapshots

Setup

1. Create a B2 bucket and application key
2. Create agenix secrets for restic/password, restic/env, restic/repo
3. Enable: atelier.backup.enable = true;

See modules/nixos/services/restic/README.md for full setup details.

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.

NixOS modules

Home-manager modules

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 = [ ... ]; }; }