Gateway Management

Gateway Management

Manage a system-level Caddy reverse proxy across your hosts. Unlike Docker-based stacks, the gateway runs as a systemd service and is managed via Caddyfile deployment.

Since: v0.24.0

Overview

The gateway command manages Caddy as a system service (not a container). This is useful when Caddy acts as the front-door reverse proxy for multiple Docker stacks on a host.

strut gateway deploy --host harbor      # Deploy Caddyfile and reload
strut gateway status --host harbor      # Check Caddy service status
strut gateway reload --host harbor      # Reload without deploying new config
strut gateway validate                  # Validate local Caddyfile syntax

File Convention

Place Caddyfile configs in your project at:

stacks/gateway/
├── Caddyfile.harbor       # Host-specific config for "harbor"
├── Caddyfile.compass      # Host-specific config for "compass"
└── Caddyfile              # Shared fallback (used if no host-specific file exists)

Resolution order:

1. stacks/gateway/Caddyfile.<host-alias> (host-specific)
2. stacks/gateway/Caddyfile (shared fallback)

Commands

gateway deploy --host <alias>

Deploys the Caddyfile to the remote host:

1. Backs up the current remote Caddyfile
2. Uploads the new config via SCP
3. Validates syntax on the remote (caddy validate)
4. Reloads Caddy service
5. Automatic rollback if validation fails

strut gateway deploy --host harbor
strut gateway deploy --host harbor --dry-run

gateway status --host <alias>

Shows systemctl status caddy on the remote host:

strut gateway status --host harbor

gateway reload --host <alias>

Reloads Caddy without deploying a new config (useful after manual remote edits):

strut gateway reload --host compass

gateway validate

Validates all local Caddyfile syntax without deploying. Requires caddy installed locally:

strut gateway validate

Configuration

Variable	Default	Description
GATEWAY_CADDY_PATH	/etc/caddy/Caddyfile	Remote path for active Caddyfile
GATEWAY_STACK_DIR	stacks/gateway	Local directory for Caddyfile configs

Set these in strut.conf to override defaults.

Host Resolution

The --host alias resolves via the [hosts] section in strut.conf (see Multi-Host Topology). Falls back to VPS_HOST / VPS_USER env vars if no topology entry exists.

Safety

• Remote config is always backed up before overwrite (.bak suffix)
• New config is validated remotely before reload
• If validation fails, the previous config is automatically restored
• Supports --dry-run for previewing the operation