Configure Cherokee web server reverse proxy and load balancing with SSL

Intermediate 45 min Apr 06, 2026 163 views
Ubuntu 24.04 Debian 12 AlmaLinux 9 Rocky Linux 9

Set up Cherokee web server with reverse proxy capabilities, load balancing across backend servers, and SSL encryption for high-performance production environments.

Prerequisites

  • Root access to the server
  • Basic knowledge of web server concepts
  • Backend application servers running on ports 8080

What this solves

Cherokee web server provides lightweight reverse proxy and load balancing capabilities for distributing traffic across backend application servers. This tutorial shows you how to configure Cherokee with SSL termination, health checks, and multiple load balancing algorithms for production environments.

Step-by-step installation

Install build dependencies and libraries

Cherokee requires compilation from source since most distributions don't include recent packages. Install the necessary development tools and SSL libraries.

sudo apt update
sudo apt install -y build-essential wget curl git autoconf libtool pkg-config
sudo apt install -y libssl-dev zlib1g-dev libpcre3-dev gettext
sudo dnf update -y
sudo dnf groupinstall -y "Development Tools"
sudo dnf install -y wget curl git autoconf libtool pkgconfig
sudo dnf install -y openssl-devel zlib-devel pcre-devel gettext

Create Cherokee user and directories

Create a dedicated user for Cherokee to run securely without root privileges. Set up the necessary directory structure with proper ownership.

sudo useradd --system --no-create-home --shell /bin/false --comment "Cherokee web server" cherokee
sudo mkdir -p /opt/cherokee /var/log/cherokee /var/run/cherokee /etc/cherokee
sudo chown -R cherokee:cherokee /var/log/cherokee /var/run/cherokee

Download and compile Cherokee from source

Download the latest Cherokee source code and compile with SSL, threading, and performance optimizations enabled.

cd /tmp
wget https://github.com/cherokee/webserver/archive/refs/heads/master.zip
unzip master.zip
cd webserver-master
./autogen.sh --prefix=/opt/cherokee --enable-ssl --enable-threading --enable-epoll --with-wwwroot=/opt/cherokee/www
make -j$(nproc)
sudo make install

Configure system PATH and libraries

Add Cherokee binaries to the system PATH and configure library paths for proper operation.

sudo ln -sf /opt/cherokee/sbin/cherokee /usr/local/sbin/cherokee
sudo ln -sf /opt/cherokee/sbin/cherokee-admin /usr/local/sbin/cherokee-admin
echo '/opt/cherokee/lib' | sudo tee /etc/ld.so.conf.d/cherokee.conf
sudo ldconfig

Generate SSL certificates

Create self-signed SSL certificates for testing or prepare directories for your production certificates. Replace with your actual SSL certificates in production.

sudo mkdir -p /etc/cherokee/ssl
sudo openssl req -x509 -nodes -days 365 -newkey rsa:2048 \
  -keyout /etc/cherokee/ssl/cherokee.key \
  -out /etc/cherokee/ssl/cherokee.crt \
  -subj "/C=US/ST=State/L=City/O=Organization/CN=example.com"
sudo chown -R root:cherokee /etc/cherokee/ssl
sudo chmod 640 /etc/cherokee/ssl/*

Create Cherokee systemd service

Set up systemd service file to manage Cherokee as a system service with automatic restart and proper security settings.

[Unit]
Description=Cherokee Web Server
After=network.target
Wants=network.target

[Service]
Type=forking
User=cherokee
Group=cherokee
ExecStart=/opt/cherokee/sbin/cherokee -d
ExecReload=/bin/kill -USR1 $MAINPID
KillMode=mixed
PrivateTmp=true
LimitNOFILE=1048576
Restart=on-failure
RestartSec=5s

[Install]
WantedBy=multi-user.target

Configure reverse proxy with load balancing

Create Cherokee configuration with reverse proxy rules, load balancing across backend servers, and health monitoring.

config!version = 001002002

Server configuration

server!bind!1!port = 80 server!bind!2!port = 443 server!bind!2!tls = 1 server!bind!2!tls!certificate = /etc/cherokee/ssl/cherokee.crt server!bind!2!tls!certificate_key = /etc/cherokee/ssl/cherokee.key server!user = cherokee server!group = cherokee server!pid_file = /var/run/cherokee/cherokee.pid server!error_log = /var/log/cherokee/error.log server!access_log = /var/log/cherokee/access.log server!timeout = 15 server!keepalive = 1 server!keepalive_max_requests = 100 server!thread_number = 50

Backend servers for load balancing

source!1!type = host source!1!nick = backend1 source!1!host = 192.168.1.10:8080 source!1!timeout = 10 source!2!type = host source!2!nick = backend2 source!2!host = 192.168.1.11:8080 source!2!timeout = 10 source!3!type = host source!3!nick = backend3 source!3!host = 192.168.1.12:8080 source!3!timeout = 10

Load balancer configuration

balancer!roundrobin!source!1 = 1 balancer!roundrobin!source!2 = 2 balancer!roundrobin!source!3 = 3

Virtual server

vserver!1!nick = example.com vserver!1!document_root = /opt/cherokee/www vserver!1!rule!1!match = default vserver!1!rule!1!handler = proxy vserver!1!rule!1!handler!balancer = roundrobin vserver!1!rule!1!handler!preserve_server_host = 1 vserver!1!rule!1!handler!preserve_host = 1 vserver!1!rule!1!handler!error_handler = 1

HTTP to HTTPS redirect

vserver!2!nick = redirect vserver!2!document_root = /opt/cherokee/www vserver!2!rule!1!match = default vserver!2!rule!1!handler = redir vserver!2!rule!1!handler!rewrite!1!show = 1 vserver!2!rule!1!handler!rewrite!1!regex = ^(.*)$ vserver!2!rule!1!handler!rewrite!1!substitution = https://example.com$1 server!bind!1!vserver = 2 server!bind!2!vserver = 1

Configure advanced load balancing options

Add health checks, failover settings, and session affinity for production environments.

# Health check configuration
source!1!env_inherited = 1
source!1!timeout = 5
source!1!ping = 30

source!2!env_inherited = 1
source!2!timeout = 5
source!2!ping = 30

source!3!env_inherited = 1
source!3!timeout = 5
source!3!ping = 30

Load balancing algorithms

Options: roundrobin, ip_hash, failover

balancer!ip_hash!source!1 = 1 balancer!ip_hash!source!2 = 2 balancer!ip_hash!source!3 = 3

Session persistence

vserver!1!rule!1!handler!balancer!policy = ip_hash

Error pages and logging

vserver!1!error_handler = 1 vserver!1!logger = combined vserver!1!logger!access!buffsize = 16384 vserver!1!logger!access!filename = /var/log/cherokee/access.log

Create Cherokee administration interface

Set up the web-based admin interface for easier configuration management. Use a secure password and limit access to trusted networks.

sudo /opt/cherokee/sbin/cherokee-admin -t -p 9090 -b 127.0.0.1 &
echo "Cherokee admin interface will be available at http://localhost:9090"
Security: The admin interface should only be accessible from localhost or trusted networks. Use a strong password and disable it when not needed.

Configure firewall rules

Open necessary ports for HTTP, HTTPS, and optionally the admin interface with proper security restrictions.

sudo ufw allow 80/tcp
sudo ufw allow 443/tcp

Only allow admin interface from localhost

sudo ufw allow from 127.0.0.1 to any port 9090
sudo firewall-cmd --permanent --add-service=http
sudo firewall-cmd --permanent --add-service=https

Only allow admin interface from localhost

sudo firewall-cmd --permanent --add-rich-rule="rule family='ipv4' source address='127.0.0.1' port protocol='tcp' port='9090' accept" sudo firewall-cmd --reload

Enable and start Cherokee service

Start Cherokee and enable it to automatically start on system boot. Check the service status to ensure proper operation.

sudo systemctl daemon-reload
sudo systemctl enable cherokee
sudo systemctl start cherokee
sudo systemctl status cherokee

Configure advanced load balancing algorithms

Set up IP hash load balancing

Configure IP hash algorithm for session persistence, ensuring users consistently reach the same backend server.

# Replace roundrobin with ip_hash in your configuration
vserver!1!rule!1!handler!balancer = ip_hash

Add weights for different backend capacities

balancer!ip_hash!source!1!weight = 3 balancer!ip_hash!source!2!weight = 2 balancer!ip_hash!source!3!weight = 1

Configure failover load balancing

Set up active-passive failover where traffic only goes to backup servers if the primary fails.

# Failover configuration
balancer!failover!source!1 = 1  # Primary server
balancer!failover!source!2 = 2  # Backup server 1
balancer!failover!source!3 = 3  # Backup server 2

Health check intervals

source!1!ping = 10 source!2!ping = 10 source!3!ping = 10

Retry failed servers every 60 seconds

source!1!retry_after = 60 source!2!retry_after = 60 source!3!retry_after = 60

Enable health monitoring

Configure comprehensive health checks with custom monitoring endpoints and automatic failover thresholds.

# Advanced health monitoring
source!1!check = /health
source!1!check!response = 200
source!1!check!timeout = 5
source!1!disabled_time = 60

source!2!check = /health
source!2!check!response = 200
source!2!check!timeout = 5
source!2!disabled_time = 60

source!3!check = /health
source!3!check!response = 200
source!3!check!timeout = 5
source!3!disabled_time = 60

Log health check results

logger!error!filename = /var/log/cherokee/health.log

Verify your setup

# Check Cherokee service status
sudo systemctl status cherokee

Test HTTP to HTTPS redirect

curl -I http://localhost

Test SSL configuration

curl -k -I https://localhost

Check backend connectivity

curl -H "Host: example.com" http://localhost

View Cherokee processes and listening ports

sudo netstat -tlnp | grep cherokee ps aux | grep cherokee

Check log files for errors

sudo tail -f /var/log/cherokee/error.log sudo tail -f /var/log/cherokee/access.log

Common issues

Symptom Cause Fix
Cherokee won't start Configuration syntax error sudo /opt/cherokee/sbin/cherokee -t to test config
SSL certificate errors Wrong certificate paths or permissions Check paths in config, verify chmod 640 on cert files
Backend servers unreachable Incorrect IP addresses or ports Test connectivity with telnet backend-ip port
Permission denied errors Cherokee user lacks file access chown cherokee:cherokee on required directories, never use chmod 777
High memory usage Too many worker threads Reduce server!thread_number in configuration
Load balancing not working All requests go to one server Verify balancer configuration and backend health status

Next steps

Automated install script

Run this to automate the entire setup

Need help?

Don't want to manage this yourself?

We handle managed cloud infrastructure for businesses that depend on uptime. From initial setup to ongoing operations.