Skip to content

tls.md

Latest commit

 

History

History
129 lines (95 loc) · 3.91 KB

tls.md

File metadata and controls

129 lines (95 loc) · 3.91 KB
Raw

TLS & Reverse Proxy

Uteke server (uteke-serve) runs plain HTTP by default. For production deployments, use a reverse proxy to add TLS termination, rate limiting, and other security features.

Quick Setup with Caddy

Caddy provides automatic HTTPS with Let's Encrypt.

Caddyfile

uteke.yourdomain.com {
    reverse_proxy localhost:8767
}

Caddy automatically provisions and renews TLS certificates.

Docker Compose

version: "3"
services:
  uteke:
    image: ghcr.io/codecoradev/uteke:latest
    command: uteke-serve --host 0.0.0.0 --auth-token YOUR_SECRET_TOKEN
    volumes:
      - uteke-data:/data
    environment:
      - UTEKE_AUTH_TOKEN=${UTEKE_AUTH_TOKEN}

  caddy:
    image: caddy:2
    ports:
      - "80:80"
      - "443:443"
    volumes:
      - ./Caddyfile:/etc/caddy/Caddyfile
      - caddy-data:/data
      - caddy-config:/config

volumes:
  uteke-data:
  caddy-data:
  caddy-config:

Quick Setup with Nginx

server {
    listen 443 ssl http2;
    server_name uteke.yourdomain.com;

    ssl_certificate /etc/letsencrypt/live/uteke.yourdomain.com/fullchain.pem;
    ssl_certificate_key /etc/letsencrypt/live/uteke.yourdomain.com/privkey.pem;

    location / {
        proxy_pass http://127.0.0.1:8767;
        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;
    }
}

Security Checklist

Item Status Details
TLS encryption ✅ Via reverse proxy Caddy (auto) or Nginx (manual Let's Encrypt)
Authentication ✅ Built-in --auth-token flag or uteke.toml [server] auth_token
CORS ✅ Built-in (off by default; "*" opts in to wildcard) --cors-origin or uteke.toml [server] cors_origins
Bind address ✅ Configurable --host 127.0.0.1 for local-only access
Host header (DNS rebinding) ✅ Built-in Loopback bind accepts only loopback Host values; add names with --allowed-host or [server] allowed_hosts
Rate limiting ⚠️ Via reverse proxy Configure in Caddy/Nginx
File permissions ✅ Built-in Owner-only (0700/0600) on data directories

Configuration

Bind to Localhost Only (Recommended)

# Only accessible from the same machine
uteke-serve --host 127.0.0.1 --auth-token YOUR_TOKEN

Allow External Access (Behind Reverse Proxy)

# Listen on all interfaces (use with reverse proxy + auth)
uteke-serve --host 0.0.0.0 --auth-token YOUR_TOKEN --cors-origin https://uteke.yourdomain.com

Host Header Validation (DNS Rebinding)

On a loopback bind (127.0.0.1, ::1, localhost) uteke-serve rejects requests whose Host header is not localhost, *.localhost or a loopback IP, with 403 Host not allowed. This blocks DNS-rebinding pages that resolve an attacker-controlled name to your machine.

If a reverse proxy forwards the public hostname to a loopback-bound server, list that name:

[server]
host = "127.0.0.1"
allowed_hosts = ["uteke.yourdomain.com"]

or uteke-serve --allowed-host uteke.yourdomain.com (repeatable; the CLI flag replaces the config list). On a non-loopback bind (e.g. 0.0.0.0 in Docker, where the service name is the Host) every Host is accepted unless allowed_hosts is set. Entries match the host with or without the port, case-insensitively. A request with no Host header is accepted.

Environment Variables

Variable Purpose
UTEKE_AUTH_TOKEN Bearer token for API authentication
UTEKE_HOME Data directory (default: ~/.codecora/uteke)

Cloudflare Tunnel

For zero-config TLS without a reverse proxy:

cloudflared tunnel --url http://localhost:8767

Cloudflare Tunnel provides TLS termination, DDoS protection, and access logging — no certificate management needed.

← Back to docs