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
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"
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
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
- Setup nginx reverse proxy with SSL certificates and security hardening for comparison with Cherokee
- Optimize NGINX performance with microcaching and worker tuning for high-traffic websites for advanced performance techniques
- Configure NGINX load balancing with health checks and automatic failover for alternative load balancing solutions
- Configure Cherokee caching and compression for improved performance
- Monitor Cherokee performance with custom dashboards and alerts
Automated install script
Run this to automate the entire setup
#!/usr/bin/env bash
set -euo pipefail
# Colors for output
RED='\033[0;31m'
GREEN='\033[0;32m'
YELLOW='\033[1;33m'
NC='\033[0m'
# Default values
DOMAIN="${1:-example.com}"
BACKEND_IP="${2:-192.168.1.10}"
BACKEND_PORT="${3:-8080}"
# Usage function
usage() {
echo "Usage: $0 [domain] [backend_ip] [backend_port]"
echo "Example: $0 mysite.com 10.0.1.100 3000"
exit 1
}
# Logging functions
log_info() { echo -e "${GREEN}[INFO]${NC} $*"; }
log_warn() { echo -e "${YELLOW}[WARN]${NC} $*"; }
log_error() { echo -e "${RED}[ERROR]${NC} $*"; }
# Cleanup function for rollback
cleanup() {
log_error "Installation failed. Performing cleanup..."
systemctl stop cherokee 2>/dev/null || true
systemctl disable cherokee 2>/dev/null || true
rm -f /etc/systemd/system/cherokee.service
rm -rf /opt/cherokee /var/log/cherokee /var/run/cherokee /etc/cherokee
userdel cherokee 2>/dev/null || true
rm -f /etc/ld.so.conf.d/cherokee.conf
ldconfig
exit 1
}
# Set trap for cleanup on error
trap cleanup ERR
# Check if running as root
if [[ $EUID -ne 0 ]]; then
log_error "This script must be run as root"
exit 1
fi
# Validate domain format
if [[ ! $DOMAIN =~ ^[a-zA-Z0-9][a-zA-Z0-9-]{1,61}[a-zA-Z0-9]\.[a-zA-Z]{2,}$ ]]; then
log_error "Invalid domain format: $DOMAIN"
usage
fi
# Detect distribution
echo "[1/8] Detecting distribution and setting up package manager..."
if [ -f /etc/os-release ]; then
. /etc/os-release
case "$ID" in
ubuntu|debian)
PKG_MGR="apt"
PKG_UPDATE="apt update"
PKG_INSTALL="apt install -y"
BUILD_GROUP=""
DEV_TOOLS="build-essential"
SSL_DEV="libssl-dev"
ZLIB_DEV="zlib1g-dev"
PCRE_DEV="libpcre3-dev"
FIREWALL_CMD="ufw"
;;
almalinux|rocky|centos|rhel|ol|fedora)
PKG_MGR="dnf"
PKG_UPDATE="dnf update -y"
PKG_INSTALL="dnf install -y"
BUILD_GROUP="Development Tools"
DEV_TOOLS=""
SSL_DEV="openssl-devel"
ZLIB_DEV="zlib-devel"
PCRE_DEV="pcre-devel"
FIREWALL_CMD="firewall-cmd"
;;
amzn)
PKG_MGR="yum"
PKG_UPDATE="yum update -y"
PKG_INSTALL="yum install -y"
BUILD_GROUP="Development Tools"
DEV_TOOLS=""
SSL_DEV="openssl-devel"
ZLIB_DEV="zlib-devel"
PCRE_DEV="pcre-devel"
FIREWALL_CMD="firewall-cmd"
;;
*)
log_error "Unsupported distribution: $ID"
exit 1
;;
esac
log_info "Detected: $PRETTY_NAME using $PKG_MGR"
else
log_error "Cannot detect distribution - /etc/os-release not found"
exit 1
fi
# Update packages and install dependencies
echo "[2/8] Installing build dependencies and libraries..."
$PKG_UPDATE
if [[ -n "$BUILD_GROUP" ]]; then
$PKG_INSTALL groupinstall "$BUILD_GROUP"
fi
$PKG_INSTALL $DEV_TOOLS wget curl git autoconf libtool pkgconfig $SSL_DEV $ZLIB_DEV $PCRE_DEV gettext
# Create Cherokee user and directories
echo "[3/8] Creating Cherokee user and directory structure..."
if ! id "cherokee" &>/dev/null; then
useradd --system --no-create-home --shell /bin/false --comment "Cherokee web server" cherokee
fi
mkdir -p /opt/cherokee /var/log/cherokee /var/run/cherokee /etc/cherokee
chown -R cherokee:cherokee /var/log/cherokee /var/run/cherokee
# Download and compile Cherokee
echo "[4/8] Downloading and compiling Cherokee from source..."
cd /tmp
rm -rf webserver-master*
wget -q https://github.com/cherokee/webserver/archive/refs/heads/master.zip
unzip -q master.zip
cd webserver-master
./autogen.sh --prefix=/opt/cherokee --enable-ssl --enable-threading --enable-epoll --with-wwwroot=/opt/cherokee/www
make -j$(nproc) >/dev/null 2>&1
make install >/dev/null 2>&1
# Configure system PATH and libraries
echo "[5/8] Configuring system PATH and libraries..."
ln -sf /opt/cherokee/sbin/cherokee /usr/local/sbin/cherokee
ln -sf /opt/cherokee/sbin/cherokee-admin /usr/local/sbin/cherokee-admin
echo '/opt/cherokee/lib' > /etc/ld.so.conf.d/cherokee.conf
ldconfig
# Generate SSL certificates
echo "[6/8] Generating SSL certificates..."
mkdir -p /etc/cherokee/ssl
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=$DOMAIN" 2>/dev/null
chown -R root:cherokee /etc/cherokee/ssl
chmod 640 /etc/cherokee/ssl/*
# Create Cherokee configuration
echo "[7/8] Creating Cherokee configuration..."
cat > /etc/cherokee/cherokee.conf << EOF
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 server configuration
source!1!type = host
source!1!nick = backend1
source!1!host = $BACKEND_IP:$BACKEND_PORT
source!1!timeout = 10
# Virtual server configuration
vserver!1!nick = $DOMAIN
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 = round_robin
vserver!1!rule!1!handler!balancer!source!1 = 1
# Default virtual server
vserver!default!nick = default
vserver!default!document_root = /opt/cherokee/www
vserver!default!rule!1!match = default
vserver!default!rule!1!handler = common
EOF
chown cherokee:cherokee /etc/cherokee/cherokee.conf
chmod 644 /etc/cherokee/cherokee.conf
# Create systemd service
cat > /etc/systemd/system/cherokee.service << 'EOF'
[Unit]
Description=Cherokee Web Server
After=network.target
Wants=network.target
[Service]
Type=forking
User=cherokee
Group=cherokee
ExecStart=/opt/cherokee/sbin/cherokee -d -C /etc/cherokee/cherokee.conf
ExecReload=/bin/kill -USR1 $MAINPID
KillMode=mixed
PrivateTmp=true
LimitNOFILE=1048576
Restart=on-failure
RestartSec=5s
[Install]
WantedBy=multi-user.target
EOF
# Enable and start Cherokee service
echo "[8/8] Configuring firewall and starting Cherokee service..."
systemctl daemon-reload
systemctl enable cherokee
# Configure firewall based on distribution
if command -v ufw >/dev/null 2>&1; then
ufw allow 80/tcp >/dev/null 2>&1 || true
ufw allow 443/tcp >/dev/null 2>&1 || true
elif command -v firewall-cmd >/dev/null 2>&1; then
firewall-cmd --permanent --add-service=http >/dev/null 2>&1 || true
firewall-cmd --permanent --add-service=https >/dev/null 2>&1 || true
firewall-cmd --reload >/dev/null 2>&1 || true
fi
systemctl start cherokee
# Verification
log_info "Cherokee Web Server installation completed successfully!"
log_info "Configuration file: /etc/cherokee/cherokee.conf"
log_info "SSL certificate: /etc/cherokee/ssl/cherokee.crt"
log_info "Backend server: $BACKEND_IP:$BACKEND_PORT"
log_info "Domain: $DOMAIN"
log_warn "Replace SSL certificates with production certificates before going live"
if systemctl is-active --quiet cherokee; then
log_info "Cherokee service is running"
else
log_error "Cherokee service failed to start"
exit 1
fi
Review the script before running. Execute with: bash install.sh