Free Certificates with Let's Encrypt

You can generate free wildcard certificates with Let’s Encrypt and use them with your Surfly installation. These certificates are valid for production deployments and are automatically trusted by all major browsers.

This guide uses lego, the Let’s Encrypt binary client written in GoLang, to generate and manage certificates.

Prerequisites

Before generating certificates, ensure you have:

Domain ownership verification - You must be able to modify DNS records for your domain
DNS provider API access - Most DNS providers offer API access for automated record management
Port 80/443 access (if using HTTP challenge) or DNS API credentials (for DNS challenge)

Install Lego Client

Download and install the lego client:

cd /tmp
wget https://github.com/go-acme/lego/releases/download/v4.6.0/lego_v4.6.0_linux_amd64.tar.gz
tar -xvf lego_v4.6.0_linux_amd64.tar.gz
sudo mv lego /usr/local/bin/lego

Verify the installation:

lego --version

Configure DNS Provider

The exact configuration depends on your DNS provider. Check the lego DNS Providers documentation for provider-specific instructions.

Example: Constellix Configuration

For Constellix DNS provider, you’ll need to export your API credentials:

export CONSTELLIX_API_KEY=your_api_key
export CONSTELLIX_SECRET_KEY=your_secret_key

Example: Cloudflare Configuration

For Cloudflare, you can use either API token or Global API key:

# Using API Token (recommended)
export CLOUDFLARE_DNS_API_TOKEN=your_api_token

# Or using Global API Key
export CLOUDFLARE_EMAIL=your_email@example.com
export CLOUDFLARE_API_KEY=your_global_api_key

Generate Certificate

Once your DNS provider is configured, generate the wildcard certificate:

export DOMAIN=yourdomain.com
export EMAIL=admin@yourdomain.com

lego -a \
  --domains=${DOMAIN} \
  --domains=*.${DOMAIN} \
  --email=${EMAIL} \
  -k rsa2048 \
  --dns constellix \
  --pem \
  run

Verify Certificate

After generation, certificates are located in ~/.lego/certificates/ folder.

List your certificates:

lego list

Check certificate details:

openssl x509 -in ~/.lego/certificates/${DOMAIN}.crt -text -noout

Install Certificate

Copy the certificate to your Surfly installation directory:

# Create certificates directory if it doesn't exist
mkdir -p ~/surfly/certs/

# Copy the certificate
cp ~/.lego/certificates/${DOMAIN}.pem ~/surfly/certs/

Certificate Renewal

Let’s Encrypt certificates must be renewed every 90 days. To renew a certificate:

Manual Renewal

# Set your environment variables again
export DOMAIN=yourdomain.com
export CONSTELLIX_API_KEY=your_api_key
export CONSTELLIX_SECRET_KEY=your_secret_key

# Renew the certificate
lego -a \
  --domains=${DOMAIN} \
  --domains=*.${DOMAIN} \
  --email=admin@yourdomain.com \
  -k rsa2048 \
  --dns constellix \
  --pem \
  renew

Copy Renewed Certificate

After renewal, copy the updated certificate:

cp ~/.lego/certificates/${DOMAIN}.pem ~/surfly/certs/

Restart Surfly Services

Restart Surfly services to load the new certificate:

systemctl --user restart ss-haproxy

Automated Renewal (Recommended)

Set up a cron job to automatically renew certificates:

# Edit crontab
crontab -e

# Add renewal job (runs weekly)
0 2 * * 0 /usr/local/bin/lego --domains=yourdomain.com --domains=*.yourdomain.com --email=admin@yourdomain.com -k rsa2048 --dns constellix --pem renew && cp ~/.lego/certificates/yourdomain.com.pem ~/haproxy/certs/ && systemctl --user restart ss-haproxy

Troubleshooting

Common Issues

DNS Propagation Delays If certificate generation fails due to DNS issues, wait a few minutes for DNS propagation and retry.

API Rate Limits Let’s Encrypt has rate limits. If you hit limits, wait before retrying or use the staging environment for testing:

# Use staging environment for testing
lego --server=https://acme-staging-v02.api.letsencrypt.org/directory [other options]

Permission Errors Ensure the certificates directory has proper permissions:

chmod 600 ~/surfly/certs/${DOMAIN}.pem
chown client:client ~/surfly/certs/${DOMAIN}.pem