SSL/TLS Configuration

Configure SSL/TLS certificates for secure HTTPS connections with automatic certificate generation, green lock browser compatibility, and comprehensive SSL management.

✨ New in v0.3.5: Complete SSL/HTTPS Support

• Automatic SSL certificates with green lock browser compatibility
• Dual domain support: *.localhost and *.local.nself.org
• New CLI commands: nself trust, nself ssl bootstrap/renew/status
• 100% service reliability with HTTPS by default
• Smart port allocation (3000-3099 for frontends, 3100+ for system services)

Overview

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

Starting with v0.3.5, SSL is enabled automatically and nself supports dual domain configurations for maximum compatibility:

Local development: *.localhost domains with automatic browser trust
Network access: *.local.nself.org domains for team sharing
Production: Custom domains with Let's Encrypt or custom certificates

Let's Encrypt (Recommended)

Automatic Certificate Generation

The easiest way to get SSL certificates for production:

# In your .env.local or .env production file:
SSL_MODE=letsencrypt
LETSENCRYPT_EMAIL=admin@yourdomain.com
DOMAIN=yourdomain.com

# Optional: Multiple domains
ADDITIONAL_DOMAINS=www.yourdomain.com,api.yourdomain.com

# Rebuild and start
nself build && nself up

Certificate Renewal

Let's Encrypt certificates are automatically renewed:

# Automatic renewal (default)
SSL_AUTO_RENEW=true
SSL_RENEW_DAYS=30  # Renew when 30 days or less remain

SSL Management Commands v0.3.5

nself v0.3.5 introduces comprehensive SSL management commands:

# Bootstrap SSL certificates (initial setup)
nself ssl bootstrap

# Check SSL certificate status
nself ssl status

# Renew public certificates (Let's Encrypt)
nself ssl renew

# Check trust status
nself trust status

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 - Automatic Setup v0.3.5

One-Command SSL Setup

✨ Enhanced in v0.3.5: Complete automatic SSL setup with dual domain support and green lock compatibility!

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

# Install SSL certificate authority and enable browser trust
nself trust

# Check trust status
nself trust status

# Your services are now accessible with green lock at:
# Localhost domains (fastest):
# - https://hasura.localhost
# - https://auth.localhost
# - https://dashboard.localhost
# - https://mailpit.localhost

# Network-accessible domains:
# - https://hasura.local.nself.org
# - https://auth.local.nself.org  
# - https://dashboard.local.nself.org
# - https://mailpit.local.nself.org

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