beyond-the-prompt/skills/nix-http-server/SKILL.md

name	description
nix-http-server	Create HTTP servers for Nix flake projects. Use when serving static files or running development servers. CRITICAL CONSTRAINT - Never suggest Python dependencies.

Nix HTTP Server Skill

Core Constraint

NEVER suggest Python-based HTTP servers (python -m http.server, etc.) All dependencies MUST come from nixpkgs only.

When to Use

• User needs to serve static files from a Nix project
• User wants to create development servers
• User needs process orchestration for multiple services
• Project has a flake.nix file

Implementation Pattern

1. Use Caddy for HTTP Serving

Caddy is the approved HTTP server because:

• Available in nixpkgs
• Supports configuration as code
• Better features than simple Python server
• Works with process-compose orchestration

2. Configuration Generation

Generate configurations at build time using Nix expressions:

makeCaddyConfig = pkgs: port: root: pkgs.writeText "Caddyfile" ''
  :${toString port} {
    root * ${root}
    file_server browse
    encode gzip
    log {
      output stdout
      format console
    }
  }
'';

OR generate at runtime for development flexibility:

# Generate Caddyfile at runtime
CADDY_CONFIG=$(mktemp)
cat > "$CADDY_CONFIG" <<EOF
:8000 {
  root * $PWD/presentation
  file_server browse
  encode gzip
}
EOF

caddy run --config "$CADDY_CONFIG" --adapter caddyfile

3. Process Orchestration

For multiple services, use process-compose:

makeProcessComposeConfig = pkgs: processes: pkgs.writeText "process-compose.yaml" (
  builtins.toJSON {
    version = "0.5";
    inherit processes;
  }
);

4. Flake App Pattern

Create apps in flake.nix that:

• Check for required directories in $PWD
• Generate configs at runtime (for dev flexibility)
• Use --tui=false for process-compose (avoids /dev/tty errors)
• Add --adapter caddyfile flag when using Caddyfile format

Example Implementation

See /Users/sscoble/Projects/beyond-the-prompt/flake.nix for working examples:

• nix run .#present - Single server
• nix run .#demo - Multiple servers with process-compose

Key Technical Details

Caddy Flags

• --config <path> - Path to config file
• --adapter caddyfile - Parse as Caddyfile format (not JSON)
• run - Run server (blocking)

Process-Compose Flags

• --tui=false - Disable TUI (required for non-interactive environments)
• -f <config> - Config file path

Runtime Config Pattern

#!/usr/bin/env bash
set -euo pipefail

# Validate directory exists
CONTENT_ROOT="$PWD/presentation"
if [ ! -d "$CONTENT_ROOT" ]; then
  echo "Error: presentation/ directory not found"
  exit 1
fi

# Generate config at runtime (allows serving from working directory)
CADDY_CONFIG=$(mktemp)
trap "rm -f $CADDY_CONFIG" EXIT

cat > "$CADDY_CONFIG" <<EOF
:8000 {
  root * $CONTENT_ROOT
  file_server browse
  encode gzip
}
EOF

# Run server
caddy run --config "$CADDY_CONFIG" --adapter caddyfile

Anti-Patterns (DO NOT DO)

❌ Never suggest python -m http.server ❌ Never suggest python3 -m http.server ❌ Never add Python to buildInputs/devShell for HTTP serving ❌ Never suggest npx http-server (requires Node.js, use nixpkgs) ❌ Never hardcode absolute paths in Nix expressions (breaks portability)

Multi-Platform Support

Always use forAllSystems pattern for cross-platform compatibility:

supportedSystems = [
  "x86_64-linux"
  "aarch64-linux"
  "x86_64-darwin"
  "aarch64-darwin"
];

forAllSystems = f: nixpkgs.lib.genAttrs supportedSystems
  (system: f system (import nixpkgs { inherit system; }));

Related Documentation

Human-readable architectural rationale in: docs/adr/002-nix-flake-architecture.md

Templates

See templates/ directory for:

• Caddyfile examples
• process-compose.yaml examples
• Flake app script templates