SSL Certificates

Secure your Supascale installation with SSL/TLS certificates. This guide covers Let's Encrypt automation and custom certificate installation.

Before you start

Supascale now checks your server before you begin and tells you what will actually work, rather than letting a request fail partway through. It detects Coolify, Traefik and other reverse proxies, spots when a domain is behind Cloudflare's proxy, and recommends a method accordingly:

• DNS validation — no downtime, and the right choice when a domain is proxied through Cloudflare or port 80 is not free.
• Automated — Supascale stops the conflicting proxy, obtains the certificate, and starts it again for you.
• Manual — step-by-step instructions if you would rather run the commands yourself.

Certbot is now installed during setup on every server. It was previously skipped on hosts that do not use a Supascale-managed web server, such as Coolify hosts, which meant certificate issuance failed later with a missing-binary error.

If a domain's DNS record is proxied (the orange cloud), the HTTP-01 challenge cannot reach your server and will fail. Either use DNS validation, or turn the proxy off temporarily while the certificate is issued. Supascale detects this and says so before you start.

Let's Encrypt (Recommended)

Let's Encrypt provides free, automated SSL certificates.

Prerequisites

• Domain pointing to your server (A record)
• Port 80 accessible, or use DNS validation instead (for the HTTP-01 challenge)
• Valid email address

Using Certbot

# Install Certbot
# Ubuntu/Debian
sudo apt install certbot

# CentOS/RHEL
sudo yum install certbot

# Request certificate
sudo certbot certonly --standalone -d supascale.yourdomain.com

# Or with Nginx plugin
sudo certbot --nginx -d supascale.yourdomain.com

Certificate Location

Certificates are stored in:

/etc/letsencrypt/live/supascale.yourdomain.com/
├── fullchain.pem    # Certificate + intermediate
├── privkey.pem      # Private key
├── cert.pem         # Certificate only
└── chain.pem        # Intermediate certificate

Auto-Renewal

Certbot sets up automatic renewal. Verify with:

# Test renewal
sudo certbot renew --dry-run

# Check renewal timer
sudo systemctl status certbot.timer

With Nginx

server {
    listen 443 ssl http2;
    server_name supascale.yourdomain.com;

    ssl_certificate /etc/letsencrypt/live/supascale.yourdomain.com/fullchain.pem;
    ssl_certificate_key /etc/letsencrypt/live/supascale.yourdomain.com/privkey.pem;

    # Modern SSL configuration
    ssl_protocols TLSv1.2 TLSv1.3;
    ssl_ciphers ECDHE-ECDSA-AES128-GCM-SHA256:ECDHE-RSA-AES128-GCM-SHA256;
    ssl_prefer_server_ciphers off;
    ssl_session_cache shared:SSL:10m;
    ssl_session_timeout 1d;

    # ... rest of configuration
}

Custom Certificates

Use your own certificates from a certificate authority.

Prepare Certificates

You'll need:

1. Certificate file (.crt or .pem)
2. Private key (.key or .pem)
3. CA bundle/chain (optional, for intermediate certs)

Combine Certificates

If you have separate cert and chain files:

# Combine cert and chain
cat your-domain.crt ca-bundle.crt > fullchain.pem

Install Certificates

# Create directory
sudo mkdir -p /etc/ssl/supascale

# Copy certificates
sudo cp fullchain.pem /etc/ssl/supascale/
sudo cp private.key /etc/ssl/supascale/

# Set permissions
sudo chmod 600 /etc/ssl/supascale/private.key
sudo chmod 644 /etc/ssl/supascale/fullchain.pem

Configure Nginx

server {
    listen 443 ssl http2;
    server_name supascale.yourdomain.com;

    ssl_certificate /etc/ssl/supascale/fullchain.pem;
    ssl_certificate_key /etc/ssl/supascale/private.key;

    # ... rest of configuration
}

Self-Signed Certificates

For development or internal use only.

Generate Self-Signed Certificate

# Create directory
mkdir -p ~/certs

# Generate certificate
openssl req -x509 -nodes -days 365 -newkey rsa:2048 \
  -keyout ~/certs/supascale.key \
  -out ~/certs/supascale.crt \
  -subj "/CN=supascale.local"

Self-signed certificates will show browser warnings. Only use for development or internal networks.

SSL Best Practices

Strong Cipher Suites

Configure modern cipher suites:

# Nginx
ssl_protocols TLSv1.2 TLSv1.3;
ssl_ciphers ECDHE-ECDSA-AES128-GCM-SHA256:ECDHE-RSA-AES128-GCM-SHA256:ECDHE-ECDSA-AES256-GCM-SHA384:ECDHE-RSA-AES256-GCM-SHA384;
ssl_prefer_server_ciphers off;

HSTS Header

Force HTTPS with HTTP Strict Transport Security:

add_header Strict-Transport-Security "max-age=31536000; includeSubDomains" always;

OCSP Stapling

Enable OCSP stapling for faster certificate verification:

ssl_stapling on;
ssl_stapling_verify on;
resolver 8.8.8.8 8.8.4.4 valid=300s;
resolver_timeout 5s;

Testing SSL Configuration

SSL Labs Test

Visit SSL Labs and enter your domain for a comprehensive SSL analysis.

Command Line Test

# Test SSL connection
openssl s_client -connect supascale.yourdomain.com:443 -servername supascale.yourdomain.com

# Check certificate expiration
echo | openssl s_client -connect supascale.yourdomain.com:443 2>/dev/null | openssl x509 -noout -dates

Certificate Renewal

Let's Encrypt

Certificates renew automatically. Manual renewal:

sudo certbot renew

Custom Certificates

Set a calendar reminder to renew before expiration. Update certificates:

# Replace certificate files
sudo cp new-fullchain.pem /etc/ssl/supascale/fullchain.pem
sudo cp new-private.key /etc/ssl/supascale/private.key

# Reload web server
sudo systemctl reload nginx

Troubleshooting

Certificate Not Trusted

1. Verify the full certificate chain is included
2. Check intermediate certificates are present
3. Verify the certificate matches the domain

Certificate Expired

1. Renew with certbot renew
2. For custom certs, request new certificate from CA

Mixed Content Warnings

1. Ensure all resources use HTTPS
2. Update NEXTAUTH_URL to use HTTPS
3. Check for hardcoded HTTP URLs in configuration