echo6-docs/vault/runbooks/expose-service-home.md

---
title: Expose Service on Home Network
type: runbook
tags:
  - proxmox
aliases: []
related:
  - [[expose-service-edge2]]
  - [[expose-service-contabo]]
  - [[caddy]]
  - [[proxmox-onboard-node]]
  - [[ct-runbook]]
updated: 2026-06-18
---
# Expose Service on Home Network

## Prerequisites
- Service running on a Proxmox CT/VM or bare metal
- Router forwards 80/443 to Utility [[caddy]] (192.168.1.101) — one-time setup
- Determine pattern: does the service have [[authentik]] OIDC?

## Steps

### 1. Determine backend target

| Has OIDC? | Proxy to | Why |
|-----------|----------|-----|
| YES | Local IP (192.168.1.x:port) | Authentik SSO protects access |
| NO | Tailscale IP (100.64.0.x:port) | Only Caddy can reach backend |

If no OIDC, service MUST have Tailscale installed and registered with Headscale first.

### 2. Issue SSL certificate

```bash
ssh root@192.168.1.241

pct exec 101 -- bash -c '
export GD_Key="<from .ref/credentials>"
export GD_Secret="<from .ref/credentials>"
/root/.acme.sh/acme.sh --issue --dns dns_gd -d <service>.echo6.co --server letsencrypt
'
```

### 3. Install certificate

```bash
pct exec 101 -- bash -c "
mkdir -p /etc/caddy/certs
/root/.acme.sh/acme.sh --install-cert -d <service>.echo6.co \
  --cert-file /etc/caddy/certs/<service>.echo6.co.crt \
  --key-file /etc/caddy/certs/<service>.echo6.co.key \
  --fullchain-file /etc/caddy/certs/<service>.echo6.co.fullchain.crt \
  --reloadcmd 'systemctl reload caddy'

chown -R caddy:caddy /etc/caddy/certs
chmod 600 /etc/caddy/certs/*.key
chmod 644 /etc/caddy/certs/*.crt
"
```

### 4. Add Caddy site block

```bash
# WITH OIDC — local IP
pct exec 101 -- bash -c "cat >> /etc/caddy/Caddyfile << 'EOF'

<service>.echo6.co {
    tls /etc/caddy/certs/<service>.echo6.co.fullchain.crt /etc/caddy/certs/<service>.echo6.co.key
    reverse_proxy 192.168.1.<X>:<PORT>
}
EOF
systemctl reload caddy"

# WITHOUT OIDC — Tailscale IP
pct exec 101 -- bash -c "cat >> /etc/caddy/Caddyfile << 'EOF'

<service>.echo6.co {
    tls /etc/caddy/certs/<service>.echo6.co.fullchain.crt /etc/caddy/certs/<service>.echo6.co.key
    reverse_proxy 100.64.0.<X>:<PORT>
}
EOF
systemctl reload caddy"
```

### 5. Add DNS record

```bash
# On TOC
source /home/zvx/projects/.ref/credentials
godaddy-dns.py add-a echo6.co <service> 199.6.36.163
```

### 6. Update service CORS (if applicable)

Add `https://<service>.echo6.co` to the service's allowed origins.

### 7. Verify

```bash
curl -I https://<service>.echo6.co
```

### 8. Update docs

- Update `~/.claude/docs/infrastructure/caddy.md` with new site block
- Update `~/.claude/docs/infrastructure/services.md` with new service
- Add credentials to `/home/zvx/projects/.ref/credentials` if applicable

## Checklist

```
□ Backend pattern chosen (OIDC → local IP, no OIDC → Tailscale IP)
□ SSL cert issued and installed via acme.sh
□ Caddy site block added to CT 101 Caddyfile
□ Caddy reloaded
□ GoDaddy DNS → 199.6.36.163
□ CORS updated if needed
□ HTTPS access verified
□ Docs updated
```