nixos-pi

NixOS flake configuration for a Raspberry Pi 3B+ home server running Docker containers, Caddy reverse proxy, and Cloudflare DDNS.

Structure

nixos-pi/
├── flake.nix                  # Entry point — pins nixpkgs
├── flake.lock                 # Lockfile (commit this!)
├── configuration.nix          # Top-level system config
├── modules/
│   ├── docker.nix             # Docker daemon + container definitions
│   ├── caddy.nix              # Reverse proxy virtual hosts
│   └── cloudflare-ddns.nix    # DDNS updater systemd service/timer
├── secrets/
|   |── README.md              # How to provision secrets (files git-ignored)
│   └── files/
|       └── cf_api_token       # Cloudflare API token (plain text)
├── containers/
│   └── compose.yml            # Reference compose file (not used at runtime)
└── .gitignore

First-time deployment

1. Prepare the PC

Boot into your existing NixOS and SSH in. Then:

# Enable flakes if not already in your base config
mkdir -p /etc/nix
echo 'experimental-features = nix-command flakes' >> /etc/nix/nix.conf

2. Copy this repo to the PC

# From your dev machine
scp -r nixos-pi/ admin@nixos-pi.local:/etc/nixos/

# Or clone from git once you've pushed it:
# git clone https://github.com/you/nixos-pi /etc/nixos

3. Provision secrets

See secrets/README.md. At minimum you need /run/secrets/cloudflare-ddns.env.

4. Create the Docker network

docker network create caddy_net

5. Apply the configuration

cd /etc/nixos
sudo nixos-rebuild switch --flake .#pi

Updating

# Pull latest changes
cd /etc/nixos && git pull

# Update nixpkgs pin
nix flake update

# Apply
sudo nixos-rebuild switch --flake .#pi

Adding a new container + subdomain

1. Add a block to containers in modules/docker.nix
2. Add a matching virtualHosts entry in modules/caddy.nix
3. Mirror it in containers/compose.yml for reference
4. Run nixos-rebuild switch --flake .#pi

Useful commands

# Check systemd service status
systemctl status docker-uptime-kuma
systemctl status caddy
systemctl status cloudflare-ddns.timer

# View DDNS logs
journalctl -u cloudflare-ddns -f

# Force a DDNS update now
systemctl start cloudflare-ddns

# Garbage-collect old Nix generations
sudo nix-collect-garbage -d