Domains & SSL

Senate provides automatic domain management and SSL certificate provisioning through its built-in Caddy reverse proxy.

Overview

When you add a domain to a service:

1. Senate configures Caddy to route traffic to your container
2. If HTTPS is enabled, Let's Encrypt automatically provisions an SSL certificate
3. Traffic is proxied from the domain to your container's port

Adding a Domain

1. Navigate to your service
2. Go to the Domains tab
3. Click Add Domain
4. Configure the domain:

5. Click Save

Domain Configuration

Host

The fully qualified domain name (FQDN):

• Subdomains: app.example.com, api.example.com
• Root domain: example.com
• Wildcard: Not currently supported

Port

The internal container port your application listens on:

• Must match the port your app binds to inside the container
• Different from host port bindings
• Common ports: 3000, 8080, 80

Path

Route specific URL paths to different services:

Protocol

SSL Certificates

Senate supports three SSL certificate modes:

Automatic (HTTP-01 Challenge)

Default mode using Let's Encrypt HTTP-01 challenge:

1. Configures Caddy with the domain
2. Caddy requests a certificate from Let's Encrypt
3. HTTP-01 challenge validates domain ownership
4. Certificate is installed and auto-renewed

Requirements:

• Domain DNS must point to your server's IP
• Port 80 must be accessible (for HTTP-01 challenge)
• Port 443 must be accessible (for HTTPS traffic)

DNS Challenge (Cloudflare)

Use DNS-01 challenge with Cloudflare DNS provider:

1. Select DNS mode when adding a domain
2. Choose Cloudflare as the DNS provider
3. Provide your Cloudflare API token
4. Caddy uses DNS-01 challenge (no port 80 required)

Use when: Port 80 is not accessible or you prefer DNS validation.

Custom Certificate

Upload your own SSL certificate:

1. Select Custom mode when adding a domain
2. Paste your certificate (PEM format)
3. Paste your private key (PEM format)
4. Certificate is used directly (no auto-renewal)

Use when: You have your own certificate or use a private CA.

Certificate Renewal

Certificates obtained via Automatic or DNS modes are automatically renewed before expiration. Custom certificates require manual renewal.

Internal Endpoints

Services also get internal endpoints for container-to-container communication:

http://{service-name}-{id}:{port}

These are displayed in the Domains tab under "Internal Endpoints."

Managing Domains

Edit Domain

1. Click the edit icon (✏️) on a domain
2. Modify the configuration
3. Click Save

Changes take effect immediately. SSL certificates are preserved.

Delete Domain

1. Click the delete icon (🗑️) on a domain
2. Confirm deletion

The route is immediately removed from Caddy.

Gateway Integration

Domains are managed by the Gateway (Caddy) on each machine. View all routes:

1. Go to Machines → Select machine → Gateway
2. See all configured domains grouped by service
3. Monitor certificate status
4. View upstream health

Troubleshooting

Certificate not provisioning

1. DNS not configured: Verify with dig yourdomain.com
2. Port 80 blocked: Check firewall allows HTTP traffic
3. Rate limited: Let's Encrypt has rate limits; wait and retry
4. Invalid domain: Ensure domain is publicly resolvable

Domain not accessible

1. Service not running: Check service status
2. Wrong port: Verify port matches container's listening port
3. Path mismatch: Check path configuration
4. Firewall: Ensure ports 80/443 are open

Best Practices

1. Always use HTTPS in production
2. Set up proper DNS before adding domains
3. Use path routing to consolidate services on fewer domains
4. Monitor Gateway status for certificate and routing issues

Related

• Custom Domain Guide - Step-by-step setup
• Gateway - Advanced routing
• Environment Variables - Configure BASE_URL