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 Emby, Jellyfin, Plex, Overseerr, Jellyseerr, and Komga

🌍 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

Installation

Prerequisites

Symptoms

QuickBox Pro v3 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

Install via qb command with automatic acme.sh setup
Configure DNS A record pointing to 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)

Basic Usage

Install Dashboard SSL Certificate

Secure your QuickBox dashboard with HTTPS:


qb install lecert --dash -d domain.com

This command:

Installs acme.sh (if not already present)
Requests SSL certificate from Let’s Encrypt
Installs certificate to /etc/nginx/ssl/domain.com/
Configures nginx reverse proxy for HTTPS
Updates QuickBox database with new web root URL

Dashboard SSL Changes Web Root

Installing a dashboard SSL certificate automatically updates your QuickBox web root to https://domain.com/. Users will access the dashboard via HTTPS instead of IP address.

Install Standalone Domain Certificate

Install a certificate for a domain not used by QuickBox dashboard:


qb install lecert --no-dash -d subdomain.domain.com

Use --no-dash when:

Setting up a subdomain for a specific application
Installing a certificate without dashboard reverse proxy
Managing multiple domains for different services

Install Application SSL Certificates

Automatically configure SSL with reverse proxy for supported applications:

Emby with SSL:


qb install lecert --emby -d emby.domain.com -u username

Jellyfin with SSL:


qb install lecert --jellyfin -d jellyfin.domain.com -u username

Plex with SSL:


qb install lecert --plex -d plex.domain.com -u username

Overseerr with SSL:


qb install lecert --overseerr -d overseerr.domain.com -u username

Jellyseerr with SSL:


qb install lecert --jellyseerr -d jellyseerr.domain.com -u username

Komga with SSL:


qb install lecert --komga -d komga.domain.com -u username

Username Required for Application SSL

When installing SSL for Emby, Jellyfin, Plex, or other applications, you must specify the username with -u flag. This ensures the reverse proxy connects to the correct user’s application instance and port.

Multiple Domains in One Command

Install certificates for multiple domains simultaneously:


qb install lecert --dash -d domain.com --emby -d emby.domain.com -u john

This single command:

Installs dashboard SSL for domain.com
Installs Emby SSL for emby.domain.com (for user john)
Configures both nginx reverse proxies
Sets up automatic renewal for both certificates

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 15+ DNS providers with acme.sh integration:

Provider	Flag/Alias	API Credentials Required
Cloudflare	`cloudflare`, `cf`	API Token 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'

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 Reference

Installation & Management Commands

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

Command Options

--dash

Install certificate for QuickBox dashboard with reverse proxy configuration

--dash -d 'domain.com'

--no-dash

Install certificate for standalone domain without dashboard reverse proxy

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

--emby

Install certificate for Emby with automatic reverse proxy setup

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

--jellyfin

Install certificate for Jellyfin with automatic reverse proxy setup

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

--plex

Install certificate for Plex with automatic reverse proxy setup

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

--overseerr

Install certificate for Overseerr with automatic reverse proxy setup

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

--jellyseerr

Install certificate for Jellyseerr with automatic reverse proxy setup

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

--komga

Install certificate for Komga with automatic reverse proxy setup

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

-dRequired

Domain name for certificate (required)

-d 'domain.com'

-uRequired

Username - this is tied to the system admin as lecert is a system-specific tool (required)

-u 'john'

--dns

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

--dns --dns-provider cloudflare

--dns-provider

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

--dns-provider cloudflare

Usage Examples

Dashboard SSL with HTTP challenge:


qb install lecert --dash -d quickbox.example.com

Dashboard SSL with wildcard certificate (DNS):


qb install lecert --dash -d '*.quickbox.io' --dns --dns-provider cloudflare

Multiple applications in one command:


qb install lecert \
  --dash -d quickbox.io \
  --jellyfin -d jellyfin.quickbox.io -u alice \
  --overseerr -d overseerr.quickbox.io -u alice

Renew certificates (automatic, but can be done manually):


qb renew lecert -d domain.com
qb renew lecert -d domain1.com -d domain2.com -d domain3.com

Accessing SSL Control Panel

QuickBox Pro includes a web-based SSL Control interface for managing certificates:

Access SSL Control

Navigate to System → SSL Control in QuickBox dashboard
Select challenge method (HTTP or DNS)
If using DNS, select provider and enter credentials
Enable certificate options:
- QuickBox Dashboard SSL
- Standalone Domain SSL
- Emby SSL (if installed)
- Jellyfin SSL (if installed)
- Plex SSL (if installed)
- Overseerr SSL (if installed)
- Jellyseerr SSL (if installed)
- Komga SSL (if installed)
Enter domain names
Click “Install Certificate”

SSL Control Features

✅ Visual interface for certificate management
✅ Credential storage for DNS providers
✅ Multiple certificates in one operation
✅ Status indicators showing existing certificates
✅ Automatic detection of installed applications

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

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
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 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