Domains, Traefik Routing & SSL Certificates

Learn how TurboV handles custom domains, path-based routing, and automatic SSL certificates via Traefik v3.

1. How Traefik Manages Traffic in TurboV

TurboV embeds Traefik v3 (traefik:v3.3.4) inside the container turbov-traefik, bound to ports 80 and 443.

Instead of writing static reverse-proxy files that require daemon reloads, the TurboV Agent writes dynamic YAML routing manifests directly to:

/var/lib/turbov/traefik/dynamic/<appId>.yml

Traefik watches this directory via filesystem notifications and updates its in-memory routing table within milliseconds without dropping active TCP connections.

2. DNS Configuration for Custom Domains

To route a domain to an application running on your server, configure your DNS provider:

Domain Type	Example	Record Type	Value
Apex Domain	`example.com`	`A`	`<Your_Server_Public_IPv4>`
Subdomain	`app.example.com`	`A` or `CNAME`	`<Your_Server_Public_IPv4>` or `example.com`
Wildcard Subdomain	`*.example.com`	`A`	`<Your_Server_Public_IPv4>`

Cloudflare DNS Instructions

If your DNS is hosted on Cloudflare, set the Proxy status to DNS Only (Grey Cloud) during the initial domain addition. This allows Let's Encrypt to verify ownership of the server IP directly. You may re-enable Cloudflare's orange cloud proxy once the certificate is generated.

3. Adding a Custom Domain

Open your application in the dashboard and select Domains.
Click Add Domain.
Enter your domain (e.g. api.yourdomain.com).
Select the target service (e.g. web).
(Optional) Configure path routing (e.g. /v1 or /auth).
Click Add & Verify.

TurboV automatically tests DNS resolution against global nameservers. Once verified, the agent writes the Traefik router manifest and initiates the SSL challenge.

4. Automated Let's Encrypt SSL Provisioning

TurboV automates the full SSL certificate lifecycle:

[ Domain Added in UI ]
         │
         ▼
[ Agent writes Traefik Router with TLS certResolver: 'letsencrypt' ]
         │
         ▼
[ Traefik contacts Let's Encrypt ACME Server ]
         │
         ▼
[ Let's Encrypt performs HTTP-01 Challenge on Port 80 ]
         │
         ▼
[ Traefik validates challenge token & receives signed TLS certificate ]
         │
         ▼
[ Certificate stored securely in /var/lib/turbov/traefik/acme.json (chmod 0600) ]
         │
         ▼
[ All HTTPS traffic encrypted on Port 443 ]

Automatic Renewal

Let's Encrypt certificates are valid for 90 days. Traefik automatically checks and renews certificates 30 days before expiration. No cron jobs or certbot scripts are required.

Automatic HTTP-to-HTTPS Redirection

All incoming traffic on port 80 is automatically upgraded to secure HTTPS (port 443) via a global 301 Permanent Redirect middleware configured in Traefik.

5. Path Routing & Multiple Domains

You can map multiple domains or subpaths to distinct services within the same environment:

Multiple Domains: Map marketing.com and app.com to the same application or different services.
Path Prefix Routing:
- example.com/api → Routes to backend service container on port 4000.
- example.com/ → Routes to frontend Next.js container on port 3000.
- Traefik automatically strips prefixes if configured using StripPrefix middleware.

6. The Fallback Maintenance Container

When an application container is restarting, redeploying, or temporarily stopped, Traefik routes incoming requests to a local fallback container:

Container Name: turbov-fallback
Image: nginx:1.27-alpine
Config: /var/lib/turbov/traefik/fallback/nginx.conf
Behavior: Serves a clean, responsive maintenance page indicating that the application is starting, rather than returning a raw 502 Bad Gateway error to end users.