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

A repeatable checklist for deploying a new self-hosted service.

===== Prerequisites =====

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

===== Checklist =====

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

<code yaml>
service-name:
  image: image:tag
  container_name: service-name
  restart: unless-stopped
  environment:
    - KEY=value
  volumes:
    - ./service/data:/data
  networks:
    - cafe_net
</code>

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

In ''caddy/Caddyfile'':

<code caddy>
@service host service.folk.zone
handle @service {
    reverse_proxy service-name:port
}
</code>

For password protection, add ''basic_auth'' inside the ''handle'' block. Generate hash:
<code bash>
docker exec cafe-caddy-1 caddy hash-password --plaintext 'password'
</code>

==== 3. Deploy ====

<code bash>
scp cafe/docker-compose.yml brennan@192.168.1.65:/home/brennan/cafe/docker-compose.yml
scp cafe/caddy/Caddyfile brennan@192.168.1.65:/home/brennan/cafe/caddy/Caddyfile
ssh brennan@192.168.1.65 "cd /home/brennan/cafe && docker compose up -d service-name"
ssh brennan@192.168.1.65 "docker exec cafe-caddy-1 caddy reload --config /etc/caddy/Caddyfile"
</code>

==== 4. Add Cloudflare Tunnel hostname ====

Zero Trust → Networks → Tunnels → ''cafe'' → Public Hostnames → Add:
  * Subdomain: ''service'', Domain: ''folk.zone'', Service: ''http://caddy:80''

**Do NOT edit the local config.yml** — it is overridden by the dashboard config.

==== 5. Add to Uptime Kuma ====

[[https://status.folk.zone]] → Add New Monitor → HTTP(s), URL: ''https://service.folk.zone'', interval: 60s.

==== 6. Add to Dashboard and Services page ====

Edit ''dashboard/index.html'' and ''dashboard/services.html'', then:
<code bash>
scp dashboard/index.html brennan@192.168.1.65:/home/brennan/cafe/dashboard/index.html
scp dashboard/services.html brennan@192.168.1.65:/home/brennan/cafe/dashboard/services.html
</code>

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

Create '':folkzone:services:service-name'' following the [[meta:start|service page template]].

===== See Also =====
  * [[guides:start|Guides Index]]

  * [[folkzone:services:caddy|Caddy]]
  * [[folkzone:services:cloudflared|Cloudflare Tunnel]]
  * [[start|Return to wiki home]]