Adding a New Service to the Homelab

A repeatable checklist for deploying a new self-hosted service on the folk.zone server (casa).

• Docker image name and version
• Decided subdomain (e.g. service.folk.zone)
• Container's internal port

The single stack lives at server/docker-compose.yml (deployed at ~/homelab/server/ on the server host):

service-name:
  image: image:tag
  container_name: folkzone-service
  restart: unless-stopped
  env_file: .env
  volumes:
    - ./service/data:/data
  networks:
    - folkzone_net

Any secrets go in server/.env (never committed).

In server/caddy/Caddyfile:

service.folk.zone {
  reverse_proxy folkzone-service:port {
    header_up Host {host}
    header_up X-Real-IP {remote}
    header_up X-Forwarded-For {remote}
    header_up X-Forwarded-Proto {scheme}
  }
}

No per-service DNS step is needed: *.folk.zone is a wildcard A record at Porkbun pointing at the public IP. Caddy issues a Let's Encrypt certificate automatically on first request.

cd ~/homelab/server
docker compose up -d service-name
docker exec folkzone-caddy caddy reload --config /etc/caddy/Caddyfile

Note: if the Caddyfile was replaced by rsync, the inode changed and caddy reload sees no diff. Use docker compose restart caddy instead. See Caddy Autosave Not Loading Config.

status.folk.zone is a custom dashboard: add the service to its config in server/status/.

Update folkzone-eleventy/src/_data/services.json (or the services section of the homepage) and rebuild with npm run build in folkzone-eleventy/.

Create :folkzone:services:service-name following an existing page such as EtherCalc.

• Guides Index
• Caddy
• Return to wiki home

Last updated: 2026-10-23