Configuration — Tunnex Documentation

The public installer keeps operator configuration in tunnex/.env. Treat tunnex.yml and release.json as signed, installer-managed release artifacts.

Core settings

Variable	Purpose	Typical value
`APP_BASE_URL`	Public web/API origin and generated email links	`https://vpn.example.com`
`TUNNEX_TLS_MODE`	Edge mode: `direct`, `terminated`, or `http`	`direct`
`TUNNEX_EDGE_LISTEN`	Installer-derived Caddy listen address	Usually leave installer-managed
`TUNNEX_COOKIE_SECURE`	Secure browser-session cookies for HTTPS	`true`
`TUNNEX_NODE_ENDPOINT`	Address issued WireGuard clients dial	`vpn.example.com:51820`
`TUNNEX_GATEWAY_CONTROL_URL`	Optional deployment-wide raw mTLS gateway endpoint	`https://cp.example.com:8443`
`TUNNEX_IPV6_POOL_CIDR`	Optional ULA pool for dual-stack device addresses	`fd7a:1b2c:3d4e::/48`
`TUNNEX_LOG_LEVEL`	API log verbosity	`info`
`TUNNEX_RELEASE_UPDATE_CHECK`	Signed online update discovery	`true` or `false`

The WireGuard endpoint is embedded in configurations at issue time. Changing TUNNEX_NODE_ENDPOINT does not repair a previously issued static profile; revoke and re-issue that device.

Organization network settings

Open Settings → Network to view the current WireGuard device pool.

Organization network settings and address pool

Select Resize only after checking every site, device, Kubernetes Service, VIP, and private DNS range for overlap.

Address-pool resize form

Existing devices and static profiles make pool changes operationally disruptive. Use a change window, retain out-of-band access, and verify both existing and new device addresses after the change.

TLS modes

Mode	Use it when	Requirement
`direct`	The Tunnex host owns public HTTPS	DNS hostname on port 443; Caddy obtains the certificate
`terminated`	A load balancer or proxy terminates TLS first	Public URL stays HTTPS; VM receives HTTP
`http`	Temporary private/evaluation deployment	Explicit `http://` URL; never present it as internet-secure

Direct https:// to a raw IP address is refused. The gateway mTLS listener on TCP 8443 is not an HTTP endpoint; use L4 passthrough rather than terminating it at an Ingress. TUNNEX_GATEWAY_CONTROL_URL must be an absolute https:// URL with no path, query, fragment, or embedded credentials.

SMTP

SMTP_HOST=smtp.example.com
SMTP_PORT=587
SMTP_FROM=no-reply@example.com
SMTP_USERNAME=...
SMTP_PASSWORD=...

Port 587 uses STARTTLS. Implicit SMTPS on port 465 is not supported by this configuration path. SMTP_FROM must be an address the provider permits.

Empty SMTP settings disable email. The console surfaces this state; local password sign-in remains available, while verification, reset, and invitation delivery do not.

Never enable MAIL_DEV_LOG on a real deployment. It logs full email bodies, including working verification, reset, and invitation links.

Apply changes

From the install directory:

cd tunnex
sudo docker compose -f tunnex.yml up -d api caddy node-agent
sudo docker compose -f tunnex.yml ps

Restart only the services affected by a change where practical. A node-agent restart can briefly interrupt the bundled gateway data path.

Secrets

The public Compose deployment generates the master encryption key, session secret, and other bootstrap secrets once in the tunnex_secrets Docker volume. They are not ordinary .env values.

Back up master.key separately from PostgreSQL. Do not rotate or regenerate it as a routine config edit: existing sealed data was encrypted under that exact key. See Backup and restore.

Inspect effective metadata

curl -fsS https://vpn.example.com/api/v1/meta

This public, non-secret response is useful for confirming edition/entitlement presentation, protocol version, enabled SSO providers, mail availability, and release metadata. It does not prove the WireGuard data plane works.

Advanced deployments

Kubernetes installations use Helm values and external PostgreSQL/Redis instead of the single-host .env. Create and custody the master-key Secret before the control plane starts. Gateway workloads require host networking and NET_ADMIN; GKE Autopilot cannot provide that execution model.