TLS/SSL Production Deployment
This guide covers deploying WhiteOwl Network Monitoring in a production environment with a trusted SSL certificate.
Overview
WhiteOwl ships with SSL enabled using a self-signed certificate. For production deployments, replace this with a trusted certificate from Let's Encrypt (free) or your organization's Certificate Authority.
What you'll do:
- Point your domain to your server
- Obtain a trusted SSL certificate
- Copy certificates to the
certs/directory - Restart the frontend container
No Docker rebuilds or configuration changes required.
Prerequisites
- WhiteOwl installed and running
- A registered domain name (e.g.,
monitor.yourcompany.com) - Root or sudo access on the host
- Ports 80 and 443 open on your firewall
Step 1: Configure DNS
Create a DNS A record pointing your domain to your server's public IP address.
| Type | Name | Value |
|---|---|---|
| A | monitor | 203.0.113.50 |
This creates monitor.yourcompany.com pointing to 203.0.113.50.
Verify DNS propagation:
nslookup monitor.yourcompany.com
Step 2: Open Firewall Ports
Ensure ports 80 and 443 are accessible:
# Ubuntu/Debian with UFW
sudo ufw allow 80/tcp
sudo ufw allow 443/tcp
sudo ufw reload
# RHEL/CentOS with firewalld
sudo firewall-cmd --permanent --add-service=http
sudo firewall-cmd --permanent --add-service=https
sudo firewall-cmd --reload
# AWS Security Group
# Add inbound rules for TCP 80 and TCP 443 from 0.0.0.0/0
Step 3: Install Certbot
Certbot automates obtaining and renewing Let's Encrypt certificates.
# Ubuntu/Debian
sudo apt update
sudo apt install certbot
# RHEL/CentOS / Amazon Linux
sudo dnf install certbot
Step 4: Obtain SSL Certificate
Stop the frontend container temporarily to free port 80:
cd /etc/chompy
sudo docker compose stop frontend
Request your certificate:
sudo certbot certonly --standalone -d monitor.yourcompany.com
Certbot will:
- Verify you control the domain
- Issue a trusted certificate
- Save files to
/etc/letsencrypt/live/monitor.yourcompany.com/
Replace monitor.yourcompany.com with your actual domain throughout this guide.
Step 5: Install Certificate
Copy the certificates to WhiteOwl's certs/ directory:
# Copy certificates
sudo cp /etc/letsencrypt/live/monitor.yourcompany.com/fullchain.pem /etc/chompy/certs/server.crt
sudo cp /etc/letsencrypt/live/monitor.yourcompany.com/privkey.pem /etc/chompy/certs/server.key
# Set permissions
sudo chmod 600 /etc/chompy/certs/server.key
sudo chmod 644 /etc/chompy/certs/server.crt
Step 6: Start WhiteOwl
cd /etc/chompy
sudo docker compose up -d frontend
Step 7: Verify
Open your browser and navigate to https://monitor.yourcompany.com. You should see:
- A valid SSL certificate (padlock icon)
- No browser security warnings
- The WhiteOwl login page
Verify from the command line:
# Check certificate is trusted
curl -I https://monitor.yourcompany.com
# Check certificate expiration
echo | openssl s_client -connect monitor.yourcompany.com:443 2>/dev/null | openssl x509 -noout -dates
Step 8: Configure Automatic Renewal
Let's Encrypt certificates expire every 90 days. Set up automatic renewal:
Create the renewal script:
sudo tee /etc/chompy/scripts/renew-certs.sh > /dev/null << 'EOF'
#!/bin/bash
set -e
DOMAIN="monitor.yourcompany.com"
CHOMPY_DIR="/etc/chompy"
# Renew certificate
certbot renew --quiet --standalone --pre-hook "docker compose -f $CHOMPY_DIR/docker-compose.yml stop frontend" --post-hook "docker compose -f $CHOMPY_DIR/docker-compose.yml start frontend"
# Copy renewed certs
cp /etc/letsencrypt/live/$DOMAIN/fullchain.pem $CHOMPY_DIR/certs/server.crt
cp /etc/letsencrypt/live/$DOMAIN/privkey.pem $CHOMPY_DIR/certs/server.key
# Reload nginx
docker exec chompy-frontend nginx -s reload 2>/dev/null || true
echo "$(date): Certificate renewal completed" >> $CHOMPY_DIR/logs/cert-renewal.log
EOF
Make it executable and schedule:
sudo chmod +x /etc/chompy/scripts/renew-certs.sh
sudo mkdir -p /etc/chompy/logs
# Add to crontab (runs daily at 3am)
echo "0 3 * * * /etc/chompy/scripts/renew-certs.sh" | sudo tee -a /etc/crontab
Test the renewal process:
sudo certbot renew --dry-run
Update Probe Configuration
After enabling trusted SSL, update your probes to use the domain name:
Edit each probe's config.yaml:
api:
endpoint: "https://monitor.yourcompany.com"
timeout: 30
skip_verify: false
Restart the probe:
sudo systemctl restart whiteowl-probe
Troubleshooting
Certificate not trusted
curl: (60) SSL certificate problem: unable to get local issuer certificate
Cause: Using self-signed certificate or certificate not properly installed.
Solution: Verify the certificate files exist and are correct:
ls -la /etc/chompy/certs/
openssl x509 -in /etc/chompy/certs/server.crt -text -noout | head -20
Port 80 already in use
Certbot error: Problem binding to port 80
Cause: Frontend container is still running.
Solution: Stop the frontend before running certbot:
cd /etc/chompy
sudo docker compose stop frontend
DNS not resolving
certbot error: DNS problem: NXDOMAIN
Cause: DNS record not propagated or incorrect.
Solution: Wait for DNS propagation and verify:
nslookup monitor.yourcompany.com
dig monitor.yourcompany.com
Certificate expired
Cause: Auto-renewal not working.
Solution: Manually renew and check cron job:
sudo certbot renew
sudo cp /etc/letsencrypt/live/monitor.yourcompany.com/fullchain.pem /etc/chompy/certs/server.crt
sudo cp /etc/letsencrypt/live/monitor.yourcompany.com/privkey.pem /etc/chompy/certs/server.key
sudo docker compose -f /etc/chompy/docker-compose.yml restart frontend
Using Your Own Certificate Authority
If your organization has its own CA, skip Let's Encrypt and install your certificates directly:
# Copy your CA-signed certificate and key
sudo cp /path/to/your/certificate.crt /etc/chompy/certs/server.crt
sudo cp /path/to/your/private.key /etc/chompy/certs/server.key
# If you have a certificate chain, concatenate them
cat /path/to/your/certificate.crt /path/to/your/ca-chain.crt | sudo tee /etc/chompy/certs/server.crt
# Set permissions
sudo chmod 600 /etc/chompy/certs/server.key
sudo chmod 644 /etc/chompy/certs/server.crt
# Restart frontend
cd /etc/chompy
sudo docker compose restart frontend
For probes to trust your internal CA, install the CA certificate on each probe host:
# Debian/Ubuntu
sudo cp your-ca.crt /usr/local/share/ca-certificates/
sudo update-ca-certificates
# RHEL/CentOS
sudo cp your-ca.crt /etc/pki/ca-trust/source/anchors/
sudo update-ca-trust
Security Recommendations
- Never use
skip_verify: truein production — Always use trusted certificates - Enable firewall — Only expose ports 80, 443, and flow collection ports (2055, 6343)
- Monitor certificate expiration — Set up alerts for certificates expiring within 14 days
- Use strong passwords — Change default credentials immediately after installation
- Keep software updated — Regularly update WhiteOwl and the host operating system