External database access

Fleetdock can expose managed databases to applications outside the private network through a Fleetdock Gateway (HAProxy). The control plane generates configuration from persisted endpoint state; HAProxy proxies TCP traffic with one public port per database.

The API never proxies database connections. Desired state lives in database_endpoints; HAProxy config is derived and reconciled by the control-plane worker.

Architecture

External app → gateway.example.com:15432 (TCP) → HAProxy → server.address:instance.port → Database

Enable the gateway

External access is off by default — turning it on publishes a 50-port range on the host, which most installs never need.

fleetdock gateway enable

That flips FLEETDOCK_GATEWAY_ENABLED, activates the gateway compose profile (HAProxy and its one-shot init, sharing /var/lib/fleetdock/gateway with the control plane), and prints the port range to open in your firewall. fleetdock gateway disable reverses it.

By hand, the equivalent is FLEETDOCK_GATEWAY_ENABLED=true in .env plus docker compose --profile gateway up -d.

Hostname

FLEETDOCK_GATEWAY_PUBLIC_HOST defaults to your main FLEETDOCK_DOMAIN. The gateway speaks raw TCP on its own ports — no vhost, no SNI, no TLS termination — so it needs no DNS record of its own.

The hostname is copied into each endpoint when public access is enabled, so changing it later does not rewrite connection URLs already issued. fleetdock domain explains how to adopt a new one.

Port range and options

FLEETDOCK_GATEWAY_PORT_RANGE_START=15432
FLEETDOCK_GATEWAY_PORT_RANGE_END=15481

The published port range and the allocator range come from the same variables. Widen one and you must widen the other, or endpoints are assigned ports that nothing forwards — a failure only external clients can see.

Optional:

FLEETDOCK_GATEWAY_DIAG_PORT=15431          # source-IP diagnostic; 0 disables it
FLEETDOCK_GATEWAY_SOURCE_IP_MODE=direct    # or proxy-protocol, behind an L4 load balancer
FLEETDOCK_GATEWAY_CONFIG_PATH=/var/lib/fleetdock/gateway/haproxy.cfg
FLEETDOCK_GATEWAY_MASTER_SOCKET=/var/lib/fleetdock/gateway/haproxy-master.sock
FLEETDOCK_GATEWAY_ADMIN_SOCKET=/var/lib/fleetdock/gateway/haproxy-admin.sock

Enable public access per database

On the database page → Connectivity → Enable public access with allowed CIDRs. Or use the API:

• POST /v1/databases/{id}/public-access — enable with CIDR allowlist
• PATCH /v1/databases/{id}/public-access — update CIDRs
• DELETE /v1/databases/{id}/public-access — disable

Check status with GET /v1/databases/{id}/connectivity.

Private vs public endpoints

Public access is disabled by default. When enabled, the gateway hostname and port stay stable across migrations — only the private backend target changes. See Migration.

Application credentials

Create scoped credentials under Application credentials on the database page (or via POST /v1/databases/{id}/credentials). Passwords are encrypted at rest; the connection URL is shown once on create or rotate.

Permission profiles:

Rotate or revoke credentials via:

• POST /v1/databases/{id}/credentials/{credentialId}/rotate
• DELETE /v1/databases/{id}/credentials/{credentialId}

Source IP fidelity

Allowlists match the source address HAProxy observes, which is not always your client's address. Getting this wrong rejects every connection, and the rejection looks like the server closing the connection immediately.

Find out what your gateway actually sees. Run this from the machine that will connect:

curl http://gateway.example.com:15431

It prints the address to allowlist.

Changing the allowlist

Edit it in place from the connectivity panel, or with PATCH /v1/databases/{id}/public-access. The assigned port is preserved, so existing clients keep working. Disabling and re-enabling allocates a different port and breaks every connection URL already handed out.

If the panel reports rejected connections with no successful sessions, the allowlist does not match where clients are arriving from — check the diagnostic port above.

What Fleetdock can and cannot verify

Endpoint status reflects those facts:

TLS

HAProxy uses TCP passthrough — it does not terminate TLS at the gateway. Clients negotiate TLS with the database directly, so the database must support it for sslmode=require to work.

tls_status is measured against the database itself: a Postgres SSLRequest probe, or the CLIENT_SSL capability bit in the MySQL/MariaDB handshake.

Security

• Public access is disabled by default
• CIDR allowlists are enforced in HAProxy (tcp-request connection reject unless …)
• Explicit 0.0.0.0/0 is required for allow-from-anywhere — the UI warns when you choose it
• Instance root credentials are never exposed for public use
• Connectivity and credential changes are written to an append-only audit_events table (not yet exposed through the API or dashboard — query it with fleetdock psql)

See Security for the full trust model.

Production

Open the gateway port range in the host firewall. The control plane cannot verify reachability from outside — firewalls, NAT and DNS sit beyond it — so this is the step most often missed. The dashboard and API stay on 443; gateway ports are separate TCP listeners on the same host.

On Linux, network_mode: host for the gateway service both avoids publishing a large port range and preserves real client addresses for allowlists.

Troubleshooting

See also Troubleshooting — Gateway.

MVP limitations

• No TLS termination at gateway (passthrough only)
• One public port per database (no hostname/SNI routing)
• The gateway must have a network route to server.address:port (same as DB admin today)
• CIDR allowlists depend on the gateway observing real client addresses — see Source IP fidelity above

API reference

Gateway and credential endpoints are documented under the Databases tag in the API reference.