Custom Domain Setup

This guide shows you how to set up custom domains for your services with automatic HTTPS via Let's Encrypt.

Prerequisites

• A running service in Senate
• A domain name you control
• DNS access to create records

Step 1: Configure DNS

Point your domain to your Senate server's IP address.

For a subdomain (recommended)

Create an A record:

app.yourdomain.com → YOUR_SERVER_IP

For a root domain

Create an A record for the root:

yourdomain.com → YOUR_SERVER_IP

Step 2: Add Domain in Senate

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

5. Click Save

Step 3: SSL Certificate

When you add an HTTPS domain, Senate automatically:

1. Requests a certificate from Let's Encrypt
2. Validates domain ownership via HTTP-01 challenge
3. Configures Caddy with the certificate
4. Sets up automatic renewal

Advanced Configuration

Multiple Domains

You can add multiple domains to a single service:

• www.yourdomain.com → Primary domain
• yourdomain.com → Redirects to primary
• app.yourdomain.com → Alternative domain

Path-Based Routing

Route different paths to different services:

yourdomain.com/         → frontend service
yourdomain.com/api/     → backend service
yourdomain.com/admin/   → admin service

Configure each path as a separate domain entry pointing to the appropriate service.

Gateway Status

Monitor your domain configuration in the machine's Gateway page:

1. Go to Machines → Select your machine → Gateway
2. View all configured routes
3. Monitor upstream health

Troubleshooting

SSL certificate not provisioning

1. Verify DNS is pointing to your server: dig app.yourdomain.com
2. Ensure port 80 is open on your firewall
3. Check Gateway status for errors
4. Wait a few minutes for Let's Encrypt rate limits

Domain not accessible

1. Verify the service is running (check Overview tab)
2. Confirm the port matches your container's exposed port
3. Check that the service container is healthy
4. Review Gateway logs for routing errors

Next Steps

• Environment Variables - Configure your app's base URL
• Monitoring - Monitor domain traffic
• Gateway - Advanced routing configuration