
This post summarizes what worked (and what hurt) when I deployed multiple self-hosted services in this repo (e.g. `dockhand`, `vaultwarden`, `Checkmate`, `Miniflux`). It focuses on repeatable defaults, pitfalls, and a practical debugging workflow.

## Goals and non-negotiables

- **Domain-only access**: Do not expose host ports for business services. Avoid `IP:port` bypassing auth or leaking admin panels.
- **Single entrypoint**: Only open `80/443` externally. Let **Traefik** handle reverse proxying, TLS, and security headers.
- **Shared middleware**: Run shared MongoDB / Redis / PostgreSQL once and reuse them across apps to reduce waste.
- **Never break userspace**: Any change must not break existing online services (routing/port/network/auth conflicts).

## Repo layout and my deployment defaults

- **One app per directory**: e.g. `dockhand/`, `vaultwarden/`, `Checkmate/`, `v2/` (Miniflux).
- **Each app has a runnable `docker-compose.yml`**: avoid scattered upstream examples under `contrib/`.
- **Shared middleware is a separate project**: `middlewares/` runs `postgres` / `mongodb` / `redis`.
  - Shared middleware joins internal networks only and exposes **no public ports**.
  - Apps join shared networks via `external` networks.
- **One Traefik network**: all services that Traefik should reach join an external network like `traefik_proxy`.
- **Prefer Docker labels** (docker provider): use file provider only for a few non-container targets or special cases.

## Standard deployment playbook (the core tricks)

### 1) Do not publish host ports

For public-facing services:

- Use `expose:` (container-network visible only) instead of `ports:` (host visible).
- Route traffic via Traefik using labels.

This immediately reduces:

- **Port conflicts** (e.g. host `3000` already in use).
- **`IP:port` bypass** risks.

### 2) Traefik labels (domain routing + TLS + security headers)

Typical label set (example):

- `traefik.enable=true`
- `traefik.http.routers.<name>.rule=Host(\`example.com\`)`
- `traefik.http.routers.<name>.entrypoints=websecure`
- `traefik.http.routers.<name>.tls.certresolver=letsencrypt`
- `traefik.http.routers.<name>.middlewares=security-headers@file`
- `traefik.http.services.<name>.loadbalancer.server.port=<container_port>`

### 3) Multi-network containers must pin the Traefik network

When a container joins both:

- `traefik_proxy` (for Traefik)
- `infra_backend` (for databases/caches)

Traefik may pick the wrong container IP (from a network Traefik cannot reach), resulting in **504 Gateway Timeout**.

Fix: add this label to the service:

- `traefik.docker.network=traefik_proxy`

This was the typical cause for Checkmate: adding it removed the 504 immediately.

## Shared middleware (`middlewares/`)

### Design principles

- **High cohesion, low coupling**: middleware provides network services only.
- **Least privilege**: no public ports by default; internal networks only.
- **Centralized persistence**: volumes managed in `middlewares/` for easier backup/migration.

### Practical notes

- Use a stable shared network name (e.g. `infra_backend`), and let apps join with `external: true`.
- Use service names in connection strings (e.g. `postgres` / `mongodb`).
- Prefer separate DB/schema/user per app to avoid data pollution.

## App-specific pitfalls I hit this time

### Dockhand (high-risk admin surface)

- **Do not publish host ports**, domain + Traefik only.
- **Always add auth**: protect it with Traefik `basicAuth`.
- Keep it simple; complexity is how incidents are born.

### Vaultwarden (Bitwarden-compatible)

This is where it is easy to “be clever” and break clients:

- **Do not put BasicAuth on the entire site**: official clients and browser extensions will fail.
- Correct approach: protect `/admin` only.
  - Client paths like `/`, `/api`, `/identity` must not be blocked by BasicAuth.
- If “the UI loads but login fails”, check:
  - whether Cloudflare is challenging API requests (see below)
  - whether `/api` is treated as ServerConfig (may require rewriting to `/api/config` in Traefik)

### Checkmate (multi-network + MongoDB)

- Sharing MongoDB + multiple networks often triggers the Traefik wrong-network issue:
  - symptoms: 504
  - fix: `traefik.docker.network=traefik_proxy`

### Miniflux (rss reader)

- Miniflux requires **PostgreSQL**. No MongoDB/Redis is needed (unless you add RSSHub/Browserless, etc.).
- `HEAD /` returning `405` can be normal as long as `GET` works; do not misdiagnose it as downtime.

## Cloudflare pitfall: clients/extensions cannot log in

I hit the same issue twice:

- Vaultwarden browser extension: Cloudflare challenge → 403
- Reeder (Google Reader API): Cloudflare challenge → 403

Common signals:

- response headers contain `server: cloudflare` + `cf-mitigated: challenge`
- requests never reach Traefik/app logs

Mitigation options (recommended order):

- **A: set the subdomain to DNS-only (grey cloud)**: the most robust, no client-side hacks needed.
- **B: keep proxy (orange cloud), but skip challenge for this host/path**:
  - at minimum allow `/api`, `/identity`, `/reader/api/0`, `/accounts/ClientLogin`, etc.

Key takeaway:

- **“It works in a browser” does not mean “it works in a client”**. Browsers can pass challenges; clients usually cannot.

## Debug playbook (fast to slow)

### 1) Decide whether the request reaches your server

- Cloudflare 403 challenge: request never reaches your server. Fix Cloudflare/WAF first.
- Traefik 404/504: request reaches Traefik, but routing/network/backend is wrong.
- Backend 4xx/5xx: request reaches the app. Inspect app logs/config.

### 2) Traefik-side debugging

- Check access logs: which router/service handled the request and what status code it returned.
- Multi-network containers: suspect missing `traefik.docker.network` first.
- Same host defined twice: suspect file-provider vs docker-provider conflicts (delete legacy file routes).

### 3) App-side debugging

- `docker logs <container>`: verify startup, listening port, DB connectivity.
- Verify you did not accidentally use `ports:` and expose/conflict host ports.

## Final security checklist (before going public)

- **No business ports published on the host** (only keep `80/443`)
- **Admin surfaces must be authenticated** (dockhand, vaultwarden `/admin`, etc.)
- **Databases/caches are never exposed to the public internet**
- **No Traefik routing conflicts** (avoid defining the same host in both file-provider and docker-provider)
- **Cloudflare must not challenge API paths** (clients/extensions/third-party integrations will break)



Practical notes from deploying multiple self-hosted services with Traefik and Docker Compose: a repeatable layout, common pitfalls, and a debugging workflow.

Self-Hosting Deployment Notes: Traefik + Docker Compose + Domain-Only Access + Shared Middleware

Comments