SSL & Certificates

FlatRun integrates with Certbot to provide automatic SSL certificate provisioning and renewal through Let's Encrypt.

How It Works

1. You configure a domain for a deployment
2. FlatRun requests a certificate from Let's Encrypt via Certbot
3. The certificate is validated using HTTP-01 or DNS-01 challenge
4. Nginx is configured to use the certificate
5. Certificates are automatically renewed before expiration

Certbot Configuration

Configure Certbot in your agent config:

certbot:
  enabled: true
  image: certbot/certbot
  email: admin@example.com
  staging: false
  certs_path: ""
  webroot_path: ""
  container_webroot_path: /var/www/certbot
  dns_provider: ""

Validation Methods

HTTP-01 (Default)

The default method. Certbot places a file in your webroot and Let's Encrypt verifies it's accessible via HTTP.

Requirements:

• Port 80 must be accessible from the internet
• Domain must point to your server
• Nginx must be running

# Nginx config for HTTP-01 validation
location /.well-known/acme-challenge/ {
    root /var/www/certbot;
}

DNS-01

Validates by creating a DNS TXT record. Useful for:

• Servers behind firewalls
• Wildcard certificates
• Non-web services

certbot:
  enabled: true
  dns_provider: cloudflare

Supported DNS providers:

• Cloudflare
• DigitalOcean
• Route53 (AWS)
• Google Cloud DNS
• And many more (via Certbot plugins)

Certificate Storage

Certificates are stored in the deployments path by default:

/var/flatrun/deployments/
└── nginx/
    └── certs/
        └── live/
            └── example.com/
                ├── fullchain.pem
                ├── privkey.pem
                └── chain.pem

Requesting Certificates

Via UI

1. Go to the Certificates page
2. Click "Request Certificate"
3. Enter the domain name
4. Select validation method
5. Click "Request"

Via API

curl -X POST "http://localhost:8090/api/certificates" \
  -H "Authorization: Bearer $TOKEN" \
  -H "Content-Type: application/json" \
  -d '{
    "domain": "blog.example.com"
  }'

Certificate Status

Certificates can be in one of these states:

Automatic Renewal

FlatRun monitors certificate expiration and can automatically renew certificates. You can also trigger manual renewal:

# Renew all certificates
curl -X POST "http://localhost:8090/api/certificates/renew" \
  -H "Authorization: Bearer $TOKEN"

Configuring SSL for Deployments

Enable SSL in the deployment's service.yml:

name: My Blog
networking:
  expose: true
  domain: blog.example.com
  port: 80

ssl:
  enabled: true
  auto_renew: true

Or configure via the UI when setting up the proxy.

Manual Certificate Installation

You can also use existing certificates by placing them in the certs directory:

# Copy your certificates
mkdir -p /var/flatrun/deployments/nginx/certs/live/example.com
cp fullchain.pem /var/flatrun/deployments/nginx/certs/live/example.com/
cp privkey.pem /var/flatrun/deployments/nginx/certs/live/example.com/

Troubleshooting

Certificate Request Failed

• Verify the domain points to your server
• Check that port 80 is accessible
• Ensure Nginx is running and serving the webroot
• Check certbot logs in the container

Rate Limits

Let's Encrypt has rate limits. If you hit them:

• Wait for the rate limit to reset (usually 1 hour to 1 week)
• Use staging mode for testing
• Request certificates for multiple subdomains together

Certificate Not Used by Nginx

• Verify the certificate path matches Nginx config
• Reload Nginx after certificate changes
• Check Nginx error logs