====== Adding a New Service to the Homelab ======

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

===== Prerequisites =====

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

===== Checklist =====

==== 1. Add to docker-compose.yml ====

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

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

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

==== 2. Add Caddy route ====

In ''server/caddy/Caddyfile'':

<code caddy>
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}
  }
}
</code>

==== 3. DNS ====

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.

==== 4. Deploy ====

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

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

==== 5. Add to status page ====

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

==== 6. Add to homepage services list ====

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

==== 7. Add a wiki page ====

Create '':folkzone:services:service-name'' following an existing page such as
[[folkzone:services:ethercalc|EtherCalc]].

===== See Also =====
  * [[guides:start|Guides Index]]
  * [[folkzone:services:caddy|Caddy]]
  * [[start|Return to wiki home]]

Last updated: 2026-10-23