SSL/TLS Configuration

Updated for nself v0.4.8

Configure SSL/TLS certificates for secure HTTPS connections with the new nself prod ssl commands, automatic certificate management, and green lock browser compatibility.

New in v0.4.8: nself prod ssl Commands

* nself prod ssl status: Check certificate status and expiry
* nself prod ssl request: Request Let's Encrypt certificates
* nself prod ssl renew: Renew certificates before expiry
* nself prod ssl verify: Verify certificate chain
* nself prod ssl self-signed: Generate self-signed certificates
* nself trust: Install trusted CA for local development

Overview

nself provides comprehensive SSL/TLS support with automatic certificate generation, browser trust management, and production-ready SSL configuration. All services run with HTTPS by default, ensuring secure connections from development to production.

SSL configuration by environment:

Local development: *.local.nself.org with nself trust for browser trust
Staging: Let's Encrypt with --staging flag to avoid rate limits
Production: Let's Encrypt or custom certificates via nself prod ssl

Let's Encrypt (Recommended)

SSL Certificate Management v0.4.8

nself v0.4.8 introduces comprehensive SSL management via nself prod ssl:

# Check current SSL certificate status
nself prod ssl status
# Shows: subject, issuer, validity dates, days until expiry

# Request a Let's Encrypt certificate
nself prod ssl request yourdomain.com --email admin@yourdomain.com

# Use staging for testing (avoids rate limits)
nself prod ssl request yourdomain.com --staging

# Request with multiple domains
nself prod ssl request yourdomain.com,www.yourdomain.com,api.yourdomain.com

Certificate Renewal

Renew certificates before they expire:

# Renew SSL certificates
nself prod ssl renew

# Force renewal even if not near expiry
nself prod ssl renew --force

# Certificate expiry is shown in status:
nself prod ssl status
# Expires in: 45 days

Certificate Verification

Verify certificate chain and configuration:

# Verify certificate chain matches private key
nself prod ssl verify

# What it checks:
# - Certificate file exists
# - Private key file exists
# - Certificate chain is valid
# - Certificate matches private key

Custom Certificates

Using Your Own Certificates

If you have certificates from a Certificate Authority:

# Configure custom SSL
SSL_MODE=custom
SSL_CERT_PATH=/path/to/certificate.crt
SSL_KEY_PATH=/path/to/private.key
SSL_CHAIN_PATH=/path/to/chain.crt  # Optional intermediate certificate

# Place certificates in ssl/ directory
mkdir -p ssl/
cp your-cert.crt ssl/certificate.crt
cp your-key.key ssl/private.key
cp your-chain.crt ssl/chain.crt

Wildcard Certificates

# For wildcard certificates (*.yourdomain.com)
SSL_MODE=custom
DOMAIN=yourdomain.com
WILDCARD_CERT=true
SSL_CERT_PATH=ssl/wildcard.crt
SSL_KEY_PATH=ssl/wildcard.key

Development SSL v0.4.8

One-Command SSL Setup

nself trust installs a local CA certificate for trusted HTTPS in development.

Get trusted SSL certificates for all your services with a single command:

# Install SSL certificate authority and enable browser trust
nself trust

# Your services are now accessible with green lock at:
# - https://api.local.nself.org     # Hasura GraphQL
# - https://auth.local.nself.org    # Authentication
# - https://admin.local.nself.org   # nself-admin
# - https://storage.local.nself.org # MinIO
# - https://mail.local.nself.org    # MailPit

# Generate self-signed certificate for a custom domain
nself prod ssl self-signed mydomain.local

What nself trust Does

Installs mkcert: Automatically downloads and installs certificate authority tools
Creates local CA: Generates a trusted certificate authority for your system
Dual domain certificates: Creates certificates for both *.localhost and *.local.nself.org
Browser integration: Installs CA certificate in system trust store
Green lock guarantee: Eliminates all browser security warnings
Cross-platform support: Works on macOS, Windows, and Linux

💡 Pro Tip: Run nself trust once per machine. The certificates work for all your nself projects automatically.

Self-Signed Certificates (Legacy)

For local development with basic HTTPS (will show browser warnings):

# Enable development SSL
SSL_MODE=self-signed
DOMAIN=local.nself.org

# nself will generate certificates automatically
# Access your app at https://local.nself.org

Manual Certificate Authority Setup

If you prefer manual setup or need custom configuration:

# Manual mkcert setup
# Install mkcert
brew install mkcert  # macOS
sudo apt install mkcert  # Ubuntu

# Create local CA
mkcert -install

# Generate certificates
mkcert local.nself.org "*.local.nself.org"

# Configure nself
SSL_MODE=custom
SSL_CERT_PATH=ssl/local.nself.org.pem
SSL_KEY_PATH=ssl/local.nself.org-key.pem

SSL Configuration Options

Security Settings

# SSL security configuration
SSL_PROTOCOLS=TLSv1.2 TLSv1.3
SSL_CIPHERS=ECDHE-RSA-AES256-GCM-SHA512:DHE-RSA-AES256-GCM-SHA512
SSL_PREFER_SERVER_CIPHERS=on
SSL_SESSION_CACHE=shared:SSL:10m
SSL_SESSION_TIMEOUT=10m

# HSTS (HTTP Strict Transport Security)
HSTS_ENABLED=true
HSTS_MAX_AGE=31536000  # 1 year
HSTS_INCLUDE_SUBDOMAINS=true
HSTS_PRELOAD=true

Certificate Validation

# Strict certificate validation
SSL_VERIFY_CLIENT=off
SSL_VERIFY_DEPTH=1

# OCSP stapling
SSL_STAPLING=on
SSL_STAPLING_VERIFY=on

Testing SSL Configuration

Certificate Verification

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

# Check certificate details
openssl x509 -in certificate.crt -text -noout

# Verify certificate expiration
openssl x509 -in certificate.crt -enddate -noout

# Test with curl
curl -I https://yourdomain.com

SSL Labs Testing

Test your SSL configuration quality:

SSL Labs: https://www.ssllabs.com/ssltest/
Target Grade: A+ rating
Check for: Protocol support, cipher strength, certificate validity

Troubleshooting SSL Issues

Common SSL Problems

Certificate Not Loading

# Check nginx SSL configuration
nself exec nginx nginx -t

# View nginx error logs
nself logs nginx | grep ssl

# Verify certificate files exist and are readable
ls -la ssl/
chmod 644 ssl/*.crt
chmod 600 ssl/*.key

Let's Encrypt Rate Limits

# If you hit rate limits:
# - Wait for rate limit to reset (weekly for most limits)
# - Use staging environment for testing
SSL_STAGING=true  # Use Let's Encrypt staging

# Then switch to production
SSL_STAGING=false

SSL Management: Use nself ssl status to check certificate health and nself ssl renew for manual renewal when needed.

Mixed Content Issues

# Ensure all content is served over HTTPS
# Check for:
# - HTTP links in HTML
# - HTTP API calls
# - HTTP resources (images, CSS, JS)

# Force HTTPS redirects
FORCE_HTTPS=true
HTTPS_REDIRECT=true

Advanced SSL Configuration

Multiple Domain Certificates

# Subject Alternative Names (SAN)
DOMAIN=yourdomain.com
ADDITIONAL_DOMAINS=www.yourdomain.com,api.yourdomain.com,admin.yourdomain.com

# Separate certificates per subdomain
SSL_MULTI_CERT=true
SSL_CERT_API=/path/to/api-cert.crt
SSL_KEY_API=/path/to/api-key.key
SSL_CERT_ADMIN=/path/to/admin-cert.crt
SSL_KEY_ADMIN=/path/to/admin-key.key

Certificate Authorities

# Different certificate providers
SSL_MODE=letsencrypt     # Free, automatic
SSL_MODE=cloudflare      # Cloudflare Origin Certificate
SSL_MODE=custom          # Your own certificates
SSL_MODE=self-signed     # Development only

Load Balancer SSL Termination

# If using a load balancer for SSL termination
SSL_TERMINATION=loadbalancer
SSL_MODE=none
FORWARDED_PROTO_ENABLED=true

# Trust proxy headers
TRUST_PROXY=true
PROXY_IPS=10.0.0.0/8,172.16.0.0/12,192.168.0.0/16

SSL Monitoring and Maintenance

Certificate Monitoring

# Monitor certificate expiration
#!/bin/bash
# check-ssl-expiry.sh

DOMAIN="yourdomain.com"
EXPIRY_DATE=$(openssl s_client -connect $DOMAIN:443 -servername $DOMAIN 2>/dev/null | openssl x509 -enddate -noout | cut -d= -f2)
EXPIRY_TIMESTAMP=$(date -d "$EXPIRY_DATE" +%s)
CURRENT_TIMESTAMP=$(date +%s)
DAYS_UNTIL_EXPIRY=$(( (EXPIRY_TIMESTAMP - CURRENT_TIMESTAMP) / 86400 ))

if [ $DAYS_UNTIL_EXPIRY -lt 30 ]; then
    echo "SSL certificate expires in $DAYS_UNTIL_EXPIRY days" | mail -s "SSL Alert" admin@yourdomain.com
fi

Automated Certificate Management

# Cron job for certificate renewal check
crontab -e

# Monitor certificate expiry weekly
0 9 * * 1 /path/to/check-ssl-expiry.sh

Automated Renewal: Use nself ssl renew for manual renewal or set up automated scripts with the status commands.

SSL Best Practices

Use Strong Ciphers: Disable weak ciphers and protocols
Enable HSTS: Force browsers to use HTTPS
Certificate Transparency: Monitor CT logs for your domain
Key Security: Protect private keys with proper file permissions
Regular Updates: Keep SSL libraries and configurations updated
Monitoring: Set up alerts for certificate expiration
Backup Certificates: Store certificates and keys securely
Test Regularly: Use SSL testing tools to verify configuration

SSL Performance Optimization

Session Resumption

# SSL session caching for performance
SSL_SESSION_CACHE=shared:SSL:10m
SSL_SESSION_TIMEOUT=10m
SSL_SESSION_TICKETS=on

OCSP Stapling

# Enable OCSP stapling for faster certificate validation
SSL_STAPLING=on
SSL_STAPLING_VERIFY=on
SSL_TRUSTED_CERTIFICATE=/path/to/chain.crt

Security Headers

HTTPS-Related Headers

# Security headers for HTTPS
SECURITY_HEADERS_ENABLED=true

# Strict Transport Security
HSTS_ENABLED=true
HSTS_MAX_AGE=31536000
HSTS_INCLUDE_SUBDOMAINS=true

# Content Security Policy
CSP_ENABLED=true
CSP_UPGRADE_INSECURE_REQUESTS=true

# Secure cookie settings
SECURE_COOKIES=true
SAME_SITE_COOKIES=strict

SSL/TLS Configuration

New in v0.4.8: nself prod ssl Commands

Overview

Let's Encrypt (Recommended)

SSL Certificate Management v0.4.8

Certificate Renewal

Certificate Verification

Custom Certificates

Using Your Own Certificates

Wildcard Certificates

Development SSL v0.4.8

One-Command SSL Setup

What nself trust Does

Self-Signed Certificates (Legacy)

Manual Certificate Authority Setup

SSL Configuration Options

Security Settings

Certificate Validation

Testing SSL Configuration

Certificate Verification

SSL Labs Testing

Troubleshooting SSL Issues

Common SSL Problems

Certificate Not Loading

Let's Encrypt Rate Limits

Mixed Content Issues

Advanced SSL Configuration

Multiple Domain Certificates

Certificate Authorities

Load Balancer SSL Termination

SSL Monitoring and Maintenance

Certificate Monitoring

Automated Certificate Management

SSL Best Practices

SSL Performance Optimization

Session Resumption

OCSP Stapling

Security Headers

HTTPS-Related Headers

Next Steps