HTTPS & SSL Configuration

SQLPage can automatically obtain and renew SSL/TLS certificates from Let’s Encrypt, making it easy to serve your application over HTTPS without manual certificate management.

Quick Start

To enable automatic HTTPS, you only need to set one configuration parameter:

{
  "https_domain": "myapp.example.com"
}

Or via environment variable:

export HTTPS_DOMAIN="myapp.example.com"

That’s it! SQLPage will:

Listen on port 443 for HTTPS connections
Automatically request a certificate from Let’s Encrypt
Renew the certificate before it expires
Cache the certificate for instant restarts

Make sure your domain’s DNS A/AAAA record points to your server’s IP address before enabling HTTPS.

How It Works

When you set https_domain, SQLPage uses the ACME protocol with the TLS-ALPN-01 challenge to automatically obtain a certificate from Let’s Encrypt. The first time you start SQLPage with HTTPS enabled:

SQLPage contacts Let’s Encrypt’s servers
Let’s Encrypt verifies you control the domain by connecting to port 443
SQLPage completes the challenge and receives a certificate
The certificate is cached locally for future use

This process takes a few extra seconds on the first startup. Subsequent startups are instant because the certificate is loaded from the cache.

Configuration Parameters

Basic HTTPS Settings

https_domain

string

Domain name to request a certificate for. Setting this parameter will automatically make SQLPage listen on port 443 and request an SSL certificate.The server will take a little bit longer to start the first time it has to request a certificate.Example: myapp.example.com

https_certificate_email

string

default:"contact@<https_domain>"

The email address to use when requesting a certificate from Let’s Encrypt. Let’s Encrypt may use this email to send expiration notices and important updates about your certificate.Example: [email protected]

https_certificate_cache_dir

string

default:"./sqlpage/https"

A writable directory where to cache the certificates, so that SQLPage can serve HTTPS traffic immediately when it restarts.The cached certificate files are stored securely and should not be committed to version control.

https_acme_directory_url

string

default:"https://acme-v02.api.letsencrypt.org/directory"

The URL of the ACME directory to use when requesting a certificate. The default points to Let’s Encrypt’s production environment.For testing, you can use Let’s Encrypt’s staging environment: https://acme-staging-v02.api.letsencrypt.org/directory

Complete Example

Configuration file (sqlpage/sqlpage.json):

{
  "https_domain": "myapp.example.com",
  "https_certificate_email": "[email protected]",
  "https_certificate_cache_dir": "./sqlpage/https",
  "database_url": "postgres://user:pass@localhost/mydb",
  "environment": "production"
}

Or via environment variables:

export HTTPS_DOMAIN="myapp.example.com"
export HTTPS_CERTIFICATE_EMAIL="[email protected]"
export HTTPS_CERTIFICATE_CACHE_DIR="./sqlpage/https"
export DATABASE_URL="postgres://user:pass@localhost/mydb"
export ENVIRONMENT="production"

Testing with Let’s Encrypt Staging

Let’s Encrypt has rate limits to prevent abuse. When testing your HTTPS setup, use the staging environment to avoid hitting these limits:

{
  "https_domain": "test.example.com",
  "https_acme_directory_url": "https://acme-staging-v02.api.letsencrypt.org/directory"
}

The staging environment issues certificates that browsers won’t trust (they’ll show a security warning). Only use staging for testing, then switch to production for real traffic.

Requirements

Port 443 must be accessible

Let’s Encrypt needs to connect to port 443 on your server to verify you control the domain. Make sure:

Your firewall allows incoming connections on port 443
Your router forwards port 443 to your server (if behind NAT)
No other service is already using port 443

Check if port 443 is free:

sudo lsof -i :443

DNS must point to your server

Before requesting a certificate, make sure your domain’s DNS A (IPv4) or AAAA (IPv6) record points to your server’s IP address.Check DNS resolution:

dig myapp.example.com
# or
nslookup myapp.example.com

Wait for DNS propagation (can take up to 48 hours, usually much faster).

Certificate cache directory must be writable

SQLPage needs to write certificate files to the cache directory. Make sure the directory exists and is writable:

mkdir -p ./sqlpage/https
chmod 700 ./sqlpage/https

The directory should only be readable by the user running SQLPage.

One certificate per domain

Each https_domain value requests a separate certificate. If you want to serve multiple domains, you’ll need to:

Use a reverse proxy (like nginx or Caddy) in front of SQLPage
Or run multiple SQLPage instances
Or use a wildcard certificate (requires DNS-01 challenge, not supported by SQLPage’s built-in HTTPS)

Using with OIDC Authentication

When using OpenID Connect (OIDC) for authentication, the host parameter should match your HTTPS domain:

{
  "https_domain": "myapp.example.com",
  "oidc_issuer_url": "https://accounts.google.com",
  "oidc_client_id": "your-client-id",
  "oidc_client_secret": "your-client-secret"
}

If https_domain is set, you don’t need to also set host - SQLPage will use https_domain for OIDC redirects.

Manual Certificate Management

If you prefer to manage certificates yourself (e.g., using Certbot, or if you already have a certificate), you can use a reverse proxy like nginx or Caddy in front of SQLPage.

Using nginx

nginx configuration:

server {
    listen 443 ssl http2;
    server_name myapp.example.com;
    
    ssl_certificate /etc/letsencrypt/live/myapp.example.com/fullchain.pem;
    ssl_certificate_key /etc/letsencrypt/live/myapp.example.com/privkey.pem;
    
    location / {
        proxy_pass http://localhost:8080;
        proxy_set_header Host $host;
        proxy_set_header X-Real-IP $remote_addr;
        proxy_set_header X-Forwarded-For $proxy_add_x_forwarded_for;
        proxy_set_header X-Forwarded-Proto $scheme;
    }
}

SQLPage configuration:

{
  "listen_on": "127.0.0.1:8080",
  "database_url": "postgres://user:pass@localhost/mydb"
}

Using Caddy

Caddy automatically handles HTTPS certificates, similar to SQLPage: Caddyfile:

myapp.example.com {
    reverse_proxy localhost:8080
}

SQLPage configuration:

{
  "listen_on": "127.0.0.1:8080",
  "database_url": "postgres://user:pass@localhost/mydb"
}

Troubleshooting

Certificate Request Fails

Error: “Failed to request certificate from Let’s Encrypt”

Check domain DNS - Verify your domain points to your server’s IP
Check port 443 accessibility - Use an online port checker
Check logs - Set RUST_LOG=sqlpage=debug to see detailed error messages
Try staging first - Use staging environment to test your setup
Check rate limits - You may have hit Let’s Encrypt’s rate limits

”Address already in use” Error

If another service is using port 443:

# Find what's using port 443
sudo lsof -i :443

# Stop the conflicting service
sudo systemctl stop nginx  # or apache2, etc.

Certificate Not Renewing

Let’s Encrypt certificates expire after 90 days. SQLPage automatically renews them, but if renewal fails:

Check certificate cache directory - Ensure it’s writable
Check logs - Look for renewal errors
Delete cached certificate - Remove files from https_certificate_cache_dir to force a fresh request
Check Let’s Encrypt status - Visit https://letsencrypt.status.io/

Browser Shows Security Warning

If you see “Your connection is not private”:

Using staging environment? - Switch to production ACME directory
Domain mismatch - Make sure you’re accessing the exact domain in https_domain
Certificate not yet issued - Wait for SQLPage to complete the first certificate request
Clock skew - Check your server’s time is accurate

Docker Considerations

When running SQLPage in Docker:

Port Mapping

Map port 443 from the container to the host:

docker run -p 443:443 -v ./sqlpage:/etc/sqlpage lovasoa/sqlpage

Volume for Certificate Cache

Mount a volume for the certificate cache to persist across container restarts:

docker run -p 443:443 \
  -v ./sqlpage:/etc/sqlpage \
  -v ./https-cache:/etc/sqlpage/https \
  -e HTTPS_DOMAIN=myapp.example.com \
  lovasoa/sqlpage

Docker Compose Example

version: '3'
services:
  sqlpage:
    image: lovasoa/sqlpage
    ports:
      - "443:443"
    volumes:
      - ./sqlpage:/etc/sqlpage
      - ./https-cache:/etc/sqlpage/https
    environment:
      - HTTPS_DOMAIN=myapp.example.com
      - [email protected]
      - DATABASE_URL=postgres://user:pass@db:5432/mydb
  
  db:
    image: postgres:15
    environment:
      - POSTGRES_PASSWORD=pass
      - POSTGRES_USER=user
      - POSTGRES_DB=mydb
    volumes:
      - postgres-data:/var/lib/postgresql/data

volumes:
  postgres-data:

Security Best Practices

Always use HTTPS in production

Never serve sensitive data over plain HTTP. Set https_domain to enable automatic HTTPS.

Protect certificate cache directory

Set restrictive permissions on the certificate cache directory:

chmod 700 ./sqlpage/https

Use strong cipher suites

SQLPage uses modern, secure cipher suites by default. No additional configuration needed.

Keep SQLPage updated

Regular updates ensure you have the latest security patches for TLS handling.

Monitor certificate expiration

While SQLPage auto-renews certificates, monitor your email for expiration notices from Let’s Encrypt.

Test your SSL configuration

Use SSL Labs to test your HTTPS configuration.

Configuration Overview

Learn about all configuration options

OIDC Authentication

Set up Single Sign-On with OpenID Connect

Deployment

Deploy SQLPage to production

Reverse Proxy Setup

Use nginx or Caddy with SQLPage

Get Started

Core Concepts

Configuration

Guides

HTTPS & SSL Configuration

Quick Start

How It Works

Configuration Parameters

Basic HTTPS Settings

Complete Example

Testing with Let’s Encrypt Staging

Requirements

Using with OIDC Authentication

Manual Certificate Management

Using nginx

Using Caddy

Troubleshooting

Certificate Request Fails

”Address already in use” Error

Certificate Not Renewing

Browser Shows Security Warning

Docker Considerations

Port Mapping

Volume for Certificate Cache

Docker Compose Example

Security Best Practices

Configuration Overview

OIDC Authentication

Deployment

Reverse Proxy Setup

Build docs developers (and LLMs) love

Get Started

Core Concepts

Configuration

Guides

​Quick Start

​How It Works

​Configuration Parameters

​Basic HTTPS Settings

​Complete Example

​Testing with Let’s Encrypt Staging

​Requirements

​Using with OIDC Authentication

​Manual Certificate Management

​Using nginx

​Using Caddy

​Troubleshooting

​Certificate Request Fails

​”Address already in use” Error

​Certificate Not Renewing

​Browser Shows Security Warning

​Docker Considerations

​Port Mapping

​Volume for Certificate Cache

​Docker Compose Example

​Security Best Practices

​Related Topics

Configuration Overview

OIDC Authentication

Deployment

Reverse Proxy Setup

Build docs developers (and LLMs) love

Quick Start

How It Works

Configuration Parameters

Basic HTTPS Settings

Complete Example

Testing with Let’s Encrypt Staging

Requirements

Using with OIDC Authentication

Manual Certificate Management

Using nginx

Using Caddy

Troubleshooting

Certificate Request Fails

”Address already in use” Error

Certificate Not Renewing

Browser Shows Security Warning

Docker Considerations

Port Mapping

Volume for Certificate Cache

Docker Compose Example

Security Best Practices

Related Topics