Skip to content

Reverse proxy

github-actions[bot] edited this page Oct 13, 2026 · 1 revision

This page is copied from docs/reverse-proxy.md whenever it changes. To correct it, open a pull request on that file.

Running CloudBank behind a reverse proxy (HTTPS)

CloudBank serves plain HTTP on port 8080. For anything beyond a trusted LAN you should terminate TLS in front of it with a reverse proxy. CloudBank's session cookie is HttpOnly, SameSite=Lax, and Secure by default — so when a proxy terminates HTTPS, keep the default (CB_SECURE_COOKIES=true). Only set CB_SECURE_COOKIES=false for a plain-HTTP install with no TLS at all.

The app needs nothing special from the proxy: forward all paths to 8080, pass the usual headers, and allow the response body to stream (file downloads and the hot backup can be large).

Caddy

Caddy gets you automatic Let's Encrypt certificates with no extra config:

finance.example.com {
    reverse_proxy cloudbank:8080
}

Nginx

server {
    listen 443 ssl;
    server_name finance.example.com;

    ssl_certificate     /etc/letsencrypt/live/finance.example.com/fullchain.pem;
    ssl_certificate_key /etc/letsencrypt/live/finance.example.com/privkey.pem;

    # Backups and the database snapshot can be large; don't cap the body.
    client_max_body_size 0;

    location / {
        proxy_pass http://cloudbank:8080;
        proxy_set_header Host              $host;
        proxy_set_header X-Real-IP         $remote_addr;
        proxy_set_header X-Forwarded-For   $proxy_add_x_forwarded_for;
        proxy_set_header X-Forwarded-Proto $scheme;
    }
}

Traefik (compose labels)

services:
  cloudbank:
    image: ghcr.io/easly1989/cloudbank:main
    labels:
      - "traefik.enable=true"
      - "traefik.http.routers.cloudbank.rule=Host(`finance.example.com`)"
      - "traefik.http.routers.cloudbank.entrypoints=websecure"
      - "traefik.http.routers.cloudbank.tls.certresolver=le"
      - "traefik.http.services.cloudbank.loadbalancer.server.port=8080"
    volumes:
      - cloudbank-data:/data
    # Keep CB_SECURE_COOKIES at its default (true) — Traefik terminates TLS.

volumes:
  cloudbank-data:

Health checks

The proxy (or your orchestrator) can probe GET /healthz, which returns {"status":"ok"} and 200 when the database is reachable. This endpoint is unauthenticated.

Notes

  • CloudBank does not need a sub-path; host it at the domain root.
  • WebSocket upgrades are not required.
  • If you put it on a sub-domain, that's all CloudBank needs — it has no hard-coded base URL.
  • Failed sign-ins are counted per address and username, and the address is the TCP peer: CloudBank deliberately ignores X-Forwarded-For, which a client can forge. Behind a proxy every visitor shares the proxy's address, so ten wrong passwords for one username within 15 minutes block that username for everyone until the window passes. Successful sign-ins are never counted.
  • Serving over HTTPS is what makes the installable PWA work. The web manifest and service worker are already inside the image, but browsers only register the service worker (offline app shell, opt-in web-push reminders) and offer Install in a secure context — i.e. HTTPS (plain http://localhost is the only exception). Behind TLS as above it just works; over plain HTTP the browser will not offer to install the app. Keep CB_SECURE_COOKIES at its default (true) when there is TLS in front.

Clone this wiki locally