Let’s Encrypt SSL

Free, automated HTTPS certificates for your QuickBox Pro installation

Let’s Encrypt is a free, automated, and open certificate authority (CA) that provides SSL/TLS certificates to enable HTTPS on your QuickBox Pro dashboard and applications. QuickBox Pro integrates Let’s Encrypt using acme.sh, supporting both HTTP and DNS challenge methods for certificate verification—making it perfect for securing public servers and internal networks alike.

Free SSL Certificates

Completely free 90-day SSL/TLS certificates with automatic renewal—no cost, no limits

HTTP Challenge

Standard verification method using port 80—perfect for publicly accessible servers

DNS Challenge

Verify domain ownership via DNS records—required for wildcard certificates and internal networks

Automatic Renewal

Certificates auto-renew before expiration with zero downtime or manual intervention

Application Integration

Automatic reverse proxy configuration for AudioBookShelf, Dispatcharr, Emby, Jellyfin, Komga, Ombi, Plex, Seerr, and Unmanic

Wildcard Support

Secure unlimited subdomains with a single wildcard certificate (*.domain.com) via DNS challenge

Multiple Domains

Install certificates for unlimited domains and subdomains in a single command

Dashboard SSL Control

User-friendly web interface for certificate management with support for 14 DNS providers

Staging and Dry-Run

Test your challenge configuration against the Let's Encrypt staging server without consuming production rate limits

Managing certificates from the Dashboard

The dashboard’s SSL Control page (System → SSL Control, /system/ssl, admin-only) is the recommended way to issue, renew, and remove Let’s Encrypt certificates. It is a visual interface over the same acme.sh engine the CLI uses.

From SSL Control you can:

Choose the challenge method — HTTP (port 80) or DNS (TXT record, required for wildcards).
For DNS, pick your provider from the dropdown and enter API credentials — they are stored for reuse.
Select what to secure: the QuickBox Dashboard, a standalone domain, or any installed application that supports SSL (it auto-detects which are installed).
Enter the domain name(s) and click Install Certificate. Renewal and removal are managed from the same page; the certificate list shows status and expiry.

Because SSL Control covers issuance, renewal, removal, and credential storage, most users never need the CLI. See SSL Control for the full walkthrough.

Prerequisites

Symptoms

QuickBox Pro installed and configured
Valid domain name pointing to your server
Port 80 accessible (for HTTP challenge) OR DNS provider API access (for DNS challenge)
Nginx web server running (automatically configured by QuickBox)

Resolution

Issue certificates from SSL Control or the qb CLI — both drive acme.sh
Configure a DNS A record pointing to the server IP
Open firewall port 80 for HTTP challenge or configure DNS API credentials
Automatic nginx reverse proxy configuration

Understanding Challenge Methods

Let’s Encrypt verifies domain ownership using one of two methods:

Which Challenge Method Should I Use?

HTTP Challenge: Standard method, requires port 80 accessible from internet
DNS Challenge: Verifies via DNS TXT records—required for wildcard certificates and servers behind firewalls

HTTP Challenge (Default)

✅ Simple, no API credentials needed
✅ Fast verification (seconds)
❌ Requires port 80 open to internet
❌ Cannot issue wildcard certificates

DNS Challenge

✅ Works for internal servers and behind firewalls
✅ Supports wildcard certificates (*.domain.com)
❌ Requires DNS provider API credentials
❌ Slightly slower verification (30-60 seconds)

Issuing certificates from the CLI (automation)

The qb lecert commands drive the same acme.sh engine as SSL Control and are suited to automation. Every issuance installs the certificate, wires the nginx reverse proxy, and sets up automatic renewal.


# Dashboard SSL — also updates the web root to https://domain.com/
qb install lecert --dash -d domain.com
 
# Standalone domain (no dashboard reverse proxy)
qb install lecert --no-dash -d subdomain.domain.com
 
# Application SSL — supply the user with -u so the proxy targets the right instance
qb install lecert --audiobookshelf -d abs.domain.com -u username
qb install lecert --dispatcharr -d dispatcharr.domain.com -u username
qb install lecert --emby -d emby.domain.com -u username
qb install lecert --jellyfin -d jellyfin.domain.com -u username
qb install lecert --komga -d komga.domain.com -u username
qb install lecert --ombi -d ombi.domain.com -u username
qb install lecert --plex -d plex.domain.com -u username
qb install lecert --seerr -d seerr.domain.com -u username
qb install lecert --unmanic -d unmanic.domain.com -u username
 
# Multiple targets in one command
qb install lecert --dash -d domain.com --emby -d emby.domain.com -u john

Dashboard SSL changes the web root

Installing a dashboard SSL certificate updates your QuickBox web root to https://domain.com/. Users then reach the dashboard over HTTPS instead of by IP.

Supported application targets are AudioBookShelf, Dispatcharr, Emby, Jellyfin, Komga, Ombi, Plex, Seerr, and Unmanic (Seerr is the unified Overseerr/Jellyseerr target — the legacy --overseerr and --jellyseerr flags still work). Each application target requires -u <username> so the reverse proxy connects to the correct user’s instance and port. For the complete flag list see the CLI Reference.

Dispatcharr is a multi-port app

Dispatcharr runs as separate gunicorn and daphne services. When you issue a certificate with --dispatcharr, QuickBox resolves both internal ports from the user’s systemd units and rebuilds the web client for the subdomain root automatically — no manual port configuration is needed.

DNS Challenge Method

Why Use DNS Challenge?

DNS challenge is required when:

🔥 Requesting wildcard certificates (*.domain.com)
🏠 Server is on internal network or behind NAT
🛡️ Firewall blocks port 80
🔒 Enhanced security (no exposed HTTP port needed)

Supported DNS Providers

QuickBox supports 14 DNS providers with acme.sh integration:

Provider	Flag/Alias	API Credentials Required
Cloudflare	`cloudflare`, `cf`	API Token (+ optional Account ID) or Global API Key + Email
AWS Route 53	`route53`	AWS Access Key ID + Secret Access Key
Namecheap	`namecheap`	API Username + API Key
GoDaddy	`godaddy`	API Key + API Secret
DigitalOcean	`digitalocean`, `do`	API Token
Linode	`linode`	API Key (v4)
OVH	`ovh`	Application Key + Secret + Consumer Key
Vultr	`vultr`	API Key
Gandi	`gandi`	LiveDNS API Key
DNSimple	`dnsimple`	OAuth Token
Hurricane Electric	`hurricane`, `he`	Username + Password
Microsoft Azure	`azure`	Subscription ID + Tenant ID + App ID + Client Secret
Google Cloud (GCP)	`gcp`	Project ID + Service Account JSON File
IONOS	`ionos`	API Prefix + Secret

DNS Challenge Examples

Wildcard certificate with Cloudflare:


qb install lecert --dash -d '*.domain.com' --dns --dns-provider cloudflare

Wildcard certificate with Route 53:


qb install lecert --dash -d '*.domain.com' --dns --dns-provider route53

Multiple domains with DNS challenge:


qb install lecert --dash -d '*.domain.com' --emby -d 'emby.domain.com' \
  --dns --dns-provider cloudflare -u john

Configuring DNS Credentials

Option 1: Interactive Setup (Recommended)

When you run a DNS challenge without configured credentials, QuickBox prompts you to set them up:


qb install lecert --dash -d '*.domain.com' --dns --dns-provider cloudflare
# QuickBox detects missing credentials and prompts for setup

Option 2: QuickBox Dashboard SSL Control

Navigate to System → SSL Control in QuickBox dashboard
Select DNS Challenge method
Choose your DNS provider from dropdown
Enter API credentials
Click “Install Certificate”

Option 3: Manual Configuration

Edit /root/.acme.sh/account.conf and add your provider’s credentials:

Cloudflare Example:


SAVED_CF_Token='your-cloudflare-api-token'
SAVED_CF_Account_ID='your-cloudflare-account-id'

Cloudflare Account ID

CF_Account_ID is recommended when using a scoped API token. It limits the token’s DNS operations to a specific Cloudflare account, preventing accidental changes to other accounts under the same email. You can find your Account ID on the Cloudflare dashboard under Overview for any domain. While not strictly required, setting it is a best practice for multi-account setups.

Route 53 Example:


SAVED_AWS_ACCESS_KEY_ID='your-aws-access-key'
SAVED_AWS_SECRET_ACCESS_KEY='your-aws-secret-key'

Credential Security

DNS API credentials are stored in /root/.acme.sh/account.conf with 600 permissions (root-only read/write). Never share this file or commit it to version control. These credentials grant full control over your DNS records.

CLI command reference

Command	Description
`qb install lecert [options]`	Issue an SSL certificate with the specified targets
`qb reinstall lecert [options]`	Reinstall a certificate (useful for fixing configuration)
`qb renew lecert -d domain.com`	Manually renew a certificate (automatic renewal is enabled)
`qb remove lecert --dash`	Remove the dashboard SSL certificate and revert to HTTP
`qb help lecert`	Display full help and usage information

Key flags: --dash / --no-dash, the application targets (--audiobookshelf, --dispatcharr, --emby, --jellyfin, --komga, --ombi, --plex, --seerr, --unmanic, plus legacy --overseerr / --jellyseerr), -d <domain> (required), -u <username> (required for application targets), --dns --dns-provider <provider> for the DNS challenge, and --staging / --dry-run for testing (see below). The full table lives in the CLI Reference.

Command options

--dash

Install a certificate for the QuickBox dashboard with reverse-proxy configuration

--dash -d 'domain.com'

--no-dash

Install a certificate for a standalone domain not used by any other software

--no-dash -d 'subdomain.domain.com'

--audiobookshelf

Install a certificate and reverse proxy for AudioBookShelf

--audiobookshelf -d 'abs.domain.com' -u username

--dispatcharr

Install a certificate and reverse proxy for Dispatcharr (resolves gunicorn/daphne ports automatically)

--dispatcharr -d 'dispatcharr.domain.com' -u username

--emby

Install a certificate and reverse proxy for Emby

--emby -d 'emby.domain.com' -u username

--jellyfin

Install a certificate and reverse proxy for Jellyfin

--jellyfin -d 'jellyfin.domain.com' -u username

--komga

Install a certificate and reverse proxy for Komga

--komga -d 'komga.domain.com' -u username

--ombi

Install a certificate and reverse proxy for Ombi

--ombi -d 'ombi.domain.com' -u username

--plex

Install a certificate and reverse proxy for Plex

--plex -d 'plex.domain.com' -u username

--seerr

Install a certificate and reverse proxy for Seerr (unified Overseerr/Jellyseerr target)

--seerr -d 'seerr.domain.com' -u username

--unmanic

Install a certificate and reverse proxy for Unmanic

--unmanic -d 'unmanic.domain.com' -u username

--overseerr / --jellyseerr

Legacy Overseerr/Jellyseerr targets (still accepted; prefer --seerr)

--overseerr -d 'overseerr.domain.com' -u username

-d, --domainRequired

Domain name for the certificate (required)

-d 'domain.com'

-u, --username

Target user for application targets — lecert is a system admin tool (required for app targets)

-u 'john'

--dns

Use the DNS challenge instead of HTTP (required for wildcards)

--dns --dns-provider cloudflare

--dns-provider

DNS provider for the DNS challenge (cloudflare, route53, godaddy, etc.)

--dns-provider cloudflare

--staging

Use the Let's Encrypt staging CA. Certificates are not browser-trusted but do not count against production rate limits

--staging

--dry-run

Validate the ACME challenge without saving or installing the certificate. Skips nginx, subdomain setup, and database writes

--dry-run


# Dashboard SSL with a wildcard certificate (DNS challenge)
qb install lecert --dash -d '*.quickbox.io' --dns --dns-provider cloudflare
 
# Renew one or more certificates manually
qb renew lecert -d domain.com

Testing and Validation

Let’s Encrypt enforces strict rate limits on production certificate issuance. Use the --staging and --dry-run flags to verify your configuration before requesting real certificates.

Avoid Rate Limit Lockouts

Let’s Encrypt allows only 5 duplicate certificates per week in production. If your challenge keeps failing and you retry repeatedly, you can lock yourself out. Always test with --staging --dry-run first.

Staging Mode

The --staging flag directs acme.sh to the Let’s Encrypt staging CA (letsencrypt_test). Certificates issued by the staging CA are not trusted by browsers, but the process is identical to production — making it ideal for verifying your DNS or HTTP challenge setup without consuming rate limits.


qb install lecert --dash -d 'domain.com' --staging

Staging certificates are installed normally (nginx config, database writes, etc.) so you can confirm the full pipeline works. When you are ready, remove the --staging flag and run the command again to get a production certificate.

Dry-Run Mode

The --dry-run flag validates the ACME challenge and then stops. It does not save the certificate, configure nginx, set up subdomains, or write to the QuickBox database. Use this to confirm that domain validation succeeds before making any changes to your server.


qb install lecert --dash -d 'domain.com' --dry-run

Combined Staging + Dry-Run

For the safest possible test, combine both flags. This validates the challenge against the staging CA with zero side effects — no certificate saved, no nginx changes, no database writes:


qb install lecert --dash -d '*.domain.com' --dns --dns-provider cloudflare --staging --dry-run

This is the recommended first step before any wildcard or DNS challenge setup.

Staging with Renewal

The --staging flag is also supported with qb renew lecert. If you originally issued a staging certificate, renew it against the same staging CA:


qb renew lecert -d domain.com --staging

Staging Certificates Are Not Trusted

Staging certificates show a browser warning because they are signed by a test CA. This is expected. Once you confirm everything works, remove --staging and issue a production certificate.

Automatic Renewal

Let’s Encrypt certificates are valid for 90 days and must be renewed before expiration. QuickBox automatically configures renewal for all certificates.

How Automatic Renewal Works

acme.sh installs a systemd timer (or cron job) during initial setup
Timer runs daily to check certificate expiration
Certificates with less than 60 days remaining are automatically renewed
nginx is reloaded after successful renewal
No downtime or manual intervention required

Verify Automatic Renewal

Check acme.sh cron/timer:


# Check systemd timer
systemctl status acme.sh.timer
 
# Or check cron
crontab -l | grep acme

View renewal logs:


cat /root/.acme.sh/acme.sh.log

Test renewal process (dry run):


/root/.acme.sh/acme.sh --renew -d domain.com --force

Certificate Files & Locations

Certificate Storage

All certificates are stored in two locations:

acme.sh certificate storage

/root/.acme.sh

domain.com_ecc/

├── domain.com.cer# Certificate

├── domain.com.key# Private key

├── ca.cer# CA certificate

└── fullchain.cer# Full chain

nginx SSL directory (used by web server)

/etc/nginx/ssl

domain.com/

├── domain.com-ssl.pem# Certificate

├── domain.com-privkey.pem# Private key

└── domain.com-fullchain.pem# Full chain (cert + CA)

SSL Configuration Files

nginx snippets:

nginx configuration

/etc/nginx

snippets/

├── ssl-params.conf# SSL parameters (ciphers, protocols)

└── letsencrypt-webroot.conf# HTTP challenge configuration

sites-enabled/

├── default# Dashboard SSL reverse proxy

├── username.emby.conf# Emby reverse proxy (if installed)

└── username.jellyfin.conf# Jellyfin reverse proxy (if installed)

Troubleshooting

Certificate Installation Fails

HTTP Challenge Failure:


# Verify port 80 is accessible
curl -I http://domain.com/.well-known/acme-challenge/test
 
# Check nginx configuration
nginx -t
systemctl status nginx
 
# Verify DNS A record
dig +short domain.com
 
# Check firewall
ufw status
iptables -L -n | grep 80

DNS Challenge Failure:


# Verify credentials are configured
cat /root/.acme.sh/account.conf | grep SAVED_
 
# Test DNS provider API manually (Cloudflare example)
curl -X GET "https://api.cloudflare.com/client/v4/user/tokens/verify" \
  -H "Authorization: Bearer YOUR_CF_TOKEN"
 
# Check acme.sh logs
cat /root/.acme.sh/acme.sh.log

Renewal Not Working


# Check acme.sh timer/cron
systemctl status acme.sh.timer
 
# Manually renew certificate
/root/.acme.sh/acme.sh --renew -d domain.com --force
 
# Check certificate expiration
openssl x509 -enddate -noout -in /etc/nginx/ssl/domain.com/domain.com-fullchain.pem
 
# Re-enable auto-renewal
/root/.acme.sh/acme.sh --install-cronjob

nginx Not Loading Certificate


# Verify certificate files exist
ls -lh /etc/nginx/ssl/domain.com/
 
# Test nginx configuration
nginx -t
 
# Reload nginx
systemctl reload nginx
 
# Check nginx error logs
tail -f /var/log/nginx/error.log

Wildcard Certificate Not Working

Wildcard Certificates Require DNS Challenge

Wildcard certificates (*.domain.com) can only be issued using DNS challenge. HTTP challenge does not support wildcards. You must use --dns --dns-provider <provider> flags.


# Correct wildcard usage
qb install lecert --dash -d '*.domain.com' --dns --dns-provider cloudflare
 
# This will FAIL (HTTP challenge doesn't support wildcards)
qb install lecert --dash -d '*.domain.com'  # ❌ Missing --dns flag

Certificate Exists But Shows Expired


# Force certificate renewal
qb reinstall lecert --dash -d domain.com
 
# Or manually renew with acme.sh
/root/.acme.sh/acme.sh --renew -d domain.com --force
 
# Verify certificate validity
openssl x509 -text -noout -in /etc/nginx/ssl/domain.com/domain.com-fullchain.pem

Best Practices

Do

Always test with --staging --dry-run before requesting production certificates, especially for wildcard or DNS challenge setups
Use DNS challenge for wildcard certificates and internal servers
Install dashboard SSL first before application-specific SSL certificates
Keep DNS API credentials secure in /root/.acme.sh/account.conf
Set CF_Account_ID when using Cloudflare scoped API tokens to limit operations to a single account
Use the QuickBox SSL Control panel for easy credential management
Test certificate renewal manually before relying on automatic renewal
Use wildcard certificates (*.domain.com) to secure multiple subdomains with one cert
Verify automatic renewal is working with 'systemctl status acme.sh.timer'
Use separate subdomains for each application (emby.domain.com, jellyfin.domain.com)

Don't

Don't test against the production Let's Encrypt server—use --staging to avoid rate limits
Don't expose port 80 if using DNS challenge—it's not required
Don't install certificates for applications before installing the applications themselves
Don't ignore certificate expiration warnings—check renewal logs if you receive them
Don't manually edit nginx SSL configs—use qb command for proper reverse proxy setup
Don't use HTTP challenge for wildcard certificates—DNS challenge is required
Don't share /root/.acme.sh/account.conf file—it contains sensitive API credentials
Don't remove acme.sh timer/cron—automatic renewal stops working without it
Don't use the same domain for multiple applications—each needs a unique subdomain or path

Applications That Benefit from SSL

Applications that depend on Let's Encrypt SSL:

🖥️

QuickBox Dashboard

Core apps that rely on Let's Encrypt SSL

QuickBox Pro DashboardSecure access to your server management interface

📺

Media Servers

Core apps that rely on Let's Encrypt SSL

EmbySecure streaming with HTTPS JellyfinEncrypted connections to media server PlexSecure remote access and sharing

🎫

Media Requests

Core apps that rely on Let's Encrypt SSL

SeerrUnified request portal (replaces Overseerr/Jellyseerr) over HTTPSOmbiSecure request management

📚

Other Applications

Core apps that rely on Let's Encrypt SSL

KomgaSecure comic/manga server accessAudioBookShelfHTTPS for the audiobook serverDispatcharrSecure IPTV/stream management (multi-port reverse proxy)UnmanicSecure library optimization interfaceAny web applicationCustom reverse proxy with SSL