Operate Web Fleet

Hosting and deployment

Web Fleet is intended to run as one self-hosted service behind HTTPS on an ordinary VPS, home server or company infrastructure.

Development status: service lifecycle and database foundations exist in development. Public release artifacts and the supported installer are still pending.

Recommended deployment shape

Internet
   │
   ▼
webfleet.company.com
   │ HTTPS
   ▼
Caddy / nginx
   │ 127.0.0.1:7336
   ▼
Web Fleet
   ├── monitoring
   ├── optional analytics ingestion
   ├── manual Audit worker
   └── SQLite or PostgreSQL

Keep the application bound to loopback when a reverse proxy terminates public HTTPS. Expose only ports 80/443 from the proxy unless your network design intentionally differs.

Listen address

Web Fleet's default listener is 127.0.0.1:7336. The foreground accepts --host and --port; both are also honored from WEBFLEET_HOST / WEBFLEET_PORT. Precedence per field is CLI flag > environment variable > default, and a port must be an integer from 1 through 65535: empty, malformed, zero, negative or oversized values fail with a clear error (never a silent fallback), whitespace-only values fail, and IPv6 hosts are bracketed.

webfleet --host 127.0.0.1 --port 7336
WEBFLEET_HOST=127.0.0.1 WEBFLEET_PORT=7336 webfleet

The legacy single-address WEBFLEET_LISTEN environment variable and the service install --listen flag are retained. An explicit --host/--port overrides WEBFLEET_LISTEN; combining --listen with --host/--port fails; and when only environment variables are involved, WEBFLEET_LISTEN combined with WEBFLEET_HOST/WEBFLEET_PORT fails clearly rather than silently picking one.

Security: binding Web Fleet to 0.0.0.0 (or any non-loopback host) exposes the backend directly to the network. That must be a deliberate choice. The recommended shape is loopback plus a trusted reverse proxy that terminates HTTPS.

Trusted reverse proxies

When a reverse proxy terminates HTTPS and forwards to Web Fleet over loopback, tell Web Fleet which proxy addresses are trusted so it can honor forwarded scheme and client information:

WEBFLEET_TRUSTED_PROXIES=127.0.0.1, ::1

Forwarded headers (X-Forwarded-Proto, X-Forwarded-For) are honored only from the configured trusted proxy addresses. An untrusted client can never spoof them to upgrade a plaintext request, change its client identity, alter OIDC redirect URIs or make the session cookie Secure. Without a trusted-proxy configuration Web Fleet treats every request as direct, detecting HTTPS only from the TLS connection itself.

Public origin for OIDC

OIDC requires a canonical external origin so the authorization callback URI never depends on the incoming Host header. Set it before enabling OIDC:

WEBFLEET_PUBLIC_URL=https://webfleet.company.com

Without this value, OIDC login and configuration are rejected with a clear error and local password authentication continues to work. X-Forwarded-Host and Forwarded are never trusted, and the configured origin is used for direct and reverse-proxy deployments alike.

Linux service

The development CLI includes a systemd service lifecycle. The eventual release documentation will pair this with verified release artifacts rather than asking operators to copy arbitrary binaries into place.

# default install (explicit 127.0.0.1:7336 recorded in the unit)
sudo webfleet service install

# explicit listener, canonical host/port recorded in ExecStart
sudo webfleet service install --host 127.0.0.1 --port 7336

# legacy single-address form (retained)
sudo webfleet service install --listen 127.0.0.1:7336

systemctl status webfleet

# verified artifact update
sudo webfleet service update ./webfleet SHA256

# restore the previous binary
sudo webfleet service rollback

Installation records the listener in the managed unit so the runtime listener survives restart and reboot: a new --host/--port install writes the pair into ExecStart, while legacy bootstrap units (WEBFLEET_LISTEN environment or --listen) keep the recorded WEBFLEET_LISTEN environment. service status and its health check use the installed process's effective listener. Existing installations keep their previously recorded listener until they are reinstalled with an explicit --host/--port.

Database placement

SQLite is appropriate for the simplest single-node deployment. PostgreSQL can run on the same private network or as a managed/private database. Do not expose PostgreSQL publicly merely for Web Fleet.

Browser Audit

Normal monitoring does not require Chromium. Install a supported browser runtime only on machines that will execute manually requested Audit jobs. Larger installations may later separate that workload from normal availability monitoring.

Backups and recovery

Back up Web Fleet before upgrades and test restoration. The development CLI supports SQLite backup/restore; public-preview documentation will include a complete recovery rehearsal.