Set up Cherokee web server with advanced caching modules and gzip compression to dramatically improve page load times and reduce bandwidth usage for high-traffic websites.
Prerequisites
- Root or sudo access
- Basic understanding of web servers
- At least 2GB RAM for optimal caching
What this solves
Cherokee web server offers built-in caching and compression features that can significantly reduce response times and bandwidth usage. This tutorial configures Cherokee's caching modules to store frequently requested content and enables gzip compression to reduce file sizes, improving performance for websites with heavy traffic or slow connections.
Step-by-step installation
Update system packages
Start by updating your package manager to ensure you have access to the latest Cherokee packages and dependencies.
sudo apt update && sudo apt upgrade -y
Install Cherokee web server
Install Cherokee along with the administration interface for easy configuration management.
sudo apt install -y cherokee cherokee-admin libcherokee-mod-libssl libcherokee-mod-streaming
Enable and start Cherokee service
Enable Cherokee to start automatically on boot and start the service immediately.
sudo systemctl enable cherokee
sudo systemctl start cherokee
sudo systemctl status cherokee
Launch Cherokee admin interface
Start the Cherokee admin interface to access the web-based configuration panel. This creates a temporary admin user and password.
sudo cherokee-admin -b
The command will output the admin URL and credentials. Keep this terminal open and access the admin interface at http://your-server-ip:9090.
Configure caching modules
Enable file caching
In the Cherokee admin interface, navigate to Virtual Servers → Default → Advanced → File Cache to enable static file caching.
Configure the following settings in the admin panel:
- Enable File Cache: Yes
- Cache Directory:
/var/lib/cherokee/cache - Max File Size:
10MB - Cache Expiry:
3600seconds
Create cache directory
Create the cache directory and set proper permissions for the Cherokee web server user.
sudo mkdir -p /var/lib/cherokee/cache
sudo chown www-data:www-data /var/lib/cherokee/cache
sudo chmod 755 /var/lib/cherokee/cache
Configure static content caching rules
In the admin interface, go to Virtual Servers → Default → Behavior and create a new rule for static content caching.
Add a new rule with these settings:
- Rule Type: Extensions
- Extensions:
css,js,png,jpg,jpeg,gif,ico,pdf,zip - Handler: Static files
- Expiration: 1 month
Enable memory caching
Navigate to Virtual Servers → Default → Advanced → Memory Cache to configure in-memory caching for frequently accessed files.
Configure these memory cache settings:
- Enable Memory Cache: Yes
- Max Memory Usage:
128MB - Max File Size:
1MB - File Extensions:
css,js,html,htm
Configure compression
Enable gzip compression
In the Cherokee admin interface, navigate to Virtual Servers → Default → Advanced → Compression to enable gzip compression.
Configure compression settings:
- Enable Compression: Yes
- Compression Level:
6(balance between CPU usage and compression ratio) - Minimum File Size:
1024bytes - Maximum File Size:
1MB
Configure compression for specific file types
Create a new behavior rule for compressible content types. Go to Virtual Servers → Default → Behavior and add a new rule.
Configure the compression rule:
- Rule Type: Extensions
- Extensions:
html,htm,css,js,xml,txt,json,svg - Handler: Static files
- Transforms: Gzip encoding
Set compression headers
Navigate to Virtual Servers → Default → Advanced → Header Ops to add compression-related headers that help browsers and proxies handle cached content correctly.
Add these header operations:
- Operation: Add
- Header:
Vary - Value:
Accept-Encoding
Performance optimization
Configure Cherokee performance settings
Navigate to General → Performance in the admin interface to optimize Cherokee's worker processes and connection handling.
Adjust these performance settings:
- Thread Number: Set to number of CPU cores × 2
- Connection Reuse: Enabled
- Sendfile: Enabled
- TCP NoDelay: Enabled
Configure timeout settings
In General → Network, optimize timeout values for better performance under load.
Set these timeout values:
- Timeout:
15seconds - Keep Alive: Enabled
- Keep Alive Requests:
500 - Keep Alive Timeout:
5seconds
Apply configuration changes
Save all changes in the admin interface and restart Cherokee to apply the new caching and compression configuration.
sudo systemctl restart cherokee
sudo systemctl status cherokee
Cache monitoring and management
Monitor cache performance
Cherokee provides built-in statistics for monitoring cache hit rates and performance. Access these through the admin interface under Status → Information.
Key metrics to monitor include:
- Cache hit ratio
- Memory cache usage
- File cache size
- Compression ratio
Set up cache cleanup automation
Create a systemd timer to automatically clean old cache files and prevent disk space issues.
[Unit]
Description=Cherokee Cache Cleanup
[Service]
Type=oneshot
User=www-data
ExecStart=/bin/find /var/lib/cherokee/cache -type f -mtime +7 -delete
ExecStart=/bin/find /var/lib/cherokee/cache -type d -empty -delete
Create cleanup timer
Create a systemd timer to run the cache cleanup daily.
[Unit]
Description=Run Cherokee cache cleanup daily
Requires=cherokee-cache-cleanup.service
[Timer]
OnCalendar=daily
Persistent=true
[Install]
WantedBy=timers.target
Enable and start the cleanup timer:
sudo systemctl daemon-reload
sudo systemctl enable cherokee-cache-cleanup.timer
sudo systemctl start cherokee-cache-cleanup.timer
Verify your setup
Test that caching and compression are working correctly by checking response headers and performance.
# Test compression
curl -H "Accept-Encoding: gzip" -I http://localhost/
Check cache headers
curl -I http://localhost/style.css
Test Cherokee status
sudo systemctl status cherokee
View cache directory
ls -la /var/lib/cherokee/cache/
You should see headers like Content-Encoding: gzip for compressed content and appropriate Cache-Control headers for cached files.
Common issues
| Symptom | Cause | Fix |
|---|---|---|
| Cache not working | Incorrect directory permissions | sudo chown -R www-data:www-data /var/lib/cherokee/cache |
| High memory usage | Memory cache too large | Reduce max memory usage in admin interface |
| Compression not applied | File size below minimum threshold | Adjust minimum file size in compression settings |
| Admin interface not accessible | Firewall blocking port 9090 | sudo ufw allow 9090/tcp or use cherokee-admin -b |
| Cache directory full | No cleanup mechanism | Enable the systemd timer for automated cleanup |
Next steps
- Monitor Cherokee web server performance with Grafana and Prometheus metrics collection
- Configure Cherokee web server with MySQL database optimization and performance tuning
- Configure Cherokee web server reverse proxy and load balancing with SSL
- Set up Cherokee with automatic SSL certificates and Let's Encrypt integration
- Configure Cherokee virtual hosts for multiple domains with SSL support
Running this in production?
Automated install script
Run this to automate the entire setup
#!/usr/bin/env bash
set -euo pipefail
# Cherokee Caching and Compression Configuration Script
# Production-quality installer for Cherokee web server with performance optimizations
# Color codes for output
readonly RED='\033[0;31m'
readonly GREEN='\033[0;32m'
readonly YELLOW='\033[1;33m'
readonly NC='\033[0m'
# Global variables
CHEROKEE_CACHE_DIR="/var/lib/cherokee/cache"
CHEROKEE_CONFIG="/etc/cherokee/cherokee.conf"
WEB_USER=""
ADMIN_PORT="9090"
# Print colored output
print_status() {
echo -e "${GREEN}[INFO]${NC} $1"
}
print_warning() {
echo -e "${YELLOW}[WARNING]${NC} $1"
}
print_error() {
echo -e "${RED}[ERROR]${NC} $1"
}
# Usage information
usage() {
echo "Usage: $0 [--admin-port PORT]"
echo " --admin-port Cherokee admin interface port (default: 9090)"
echo " --help Show this help message"
exit 1
}
# Parse command line arguments
while [[ $# -gt 0 ]]; do
case $1 in
--admin-port)
ADMIN_PORT="$2"
shift 2
;;
--help)
usage
;;
*)
echo "Unknown option: $1"
usage
;;
esac
done
# Check if running as root or with sudo
check_privileges() {
if [[ $EUID -ne 0 ]]; then
print_error "This script must be run as root or with sudo"
exit 1
fi
}
# Cleanup function for rollback
cleanup() {
local exit_code=$?
if [[ $exit_code -ne 0 ]]; then
print_error "Script failed. Cleaning up..."
systemctl stop cherokee 2>/dev/null || true
systemctl disable cherokee 2>/dev/null || true
rm -rf "$CHEROKEE_CACHE_DIR" 2>/dev/null || true
fi
exit $exit_code
}
# Set trap for cleanup
trap cleanup ERR
# Auto-detect distribution
detect_distro() {
if [[ ! -f /etc/os-release ]]; then
print_error "Cannot detect distribution: /etc/os-release not found"
exit 1
fi
. /etc/os-release
case "$ID" in
ubuntu|debian)
PKG_MGR="apt"
PKG_UPDATE="apt update && apt upgrade -y"
PKG_INSTALL="apt install -y"
WEB_USER="www-data"
;;
almalinux|rocky|centos|rhel|ol|fedora)
PKG_MGR="dnf"
PKG_UPDATE="dnf update -y"
PKG_INSTALL="dnf install -y"
WEB_USER="cherokee"
;;
amzn)
PKG_MGR="yum"
PKG_UPDATE="yum update -y"
PKG_INSTALL="yum install -y"
WEB_USER="cherokee"
;;
*)
print_error "Unsupported distribution: $ID"
exit 1
;;
esac
print_status "Detected distribution: $ID"
}
# Update system packages
update_system() {
print_status "[1/8] Updating system packages..."
eval "$PKG_UPDATE"
}
# Install Cherokee and dependencies
install_cherokee() {
print_status "[2/8] Installing Cherokee web server..."
if [[ "$PKG_MGR" == "apt" ]]; then
$PKG_INSTALL cherokee cherokee-admin libcherokee-mod-libssl libcherokee-mod-streaming
else
# For RHEL-based systems, enable EPEL repository if needed
if ! command -v cherokee &> /dev/null; then
$PKG_INSTALL epel-release || true
fi
$PKG_INSTALL cherokee cherokee-admin
fi
}
# Configure Cherokee user and permissions
setup_user() {
print_status "[3/8] Setting up Cherokee user and permissions..."
# Create web user if it doesn't exist
if ! id "$WEB_USER" &>/dev/null; then
if [[ "$PKG_MGR" == "apt" ]]; then
useradd --system --no-create-home --shell /bin/false "$WEB_USER"
else
useradd --system --no-create-home --shell /sbin/nologin "$WEB_USER"
fi
fi
}
# Create and configure cache directory
setup_cache_directory() {
print_status "[4/8] Setting up cache directory..."
mkdir -p "$CHEROKEE_CACHE_DIR"
chown "$WEB_USER":"$WEB_USER" "$CHEROKEE_CACHE_DIR"
chmod 755 "$CHEROKEE_CACHE_DIR"
# Set SELinux context for RHEL-based systems
if command -v setsebool &> /dev/null; then
setsebool -P httpd_can_network_connect on || true
if command -v semanage &> /dev/null; then
semanage fcontext -a -t httpd_cache_t "$CHEROKEE_CACHE_DIR(/.*)?" || true
restorecon -R "$CHEROKEE_CACHE_DIR" || true
fi
fi
}
# Configure Cherokee basic settings
configure_cherokee() {
print_status "[5/8] Configuring Cherokee performance settings..."
# Backup original config
if [[ -f "$CHEROKEE_CONFIG" ]]; then
cp "$CHEROKEE_CONFIG" "${CHEROKEE_CONFIG}.backup.$(date +%s)"
fi
# Create basic Cherokee configuration with caching and compression
cat > "$CHEROKEE_CONFIG" << EOF
# Cherokee Configuration - Generated by install script
config!version = 001002002
# Server settings
server!bind!1!port = 80
server!user = $WEB_USER
server!group = $WEB_USER
server!pid_file = /var/run/cherokee.pid
server!thread_number = $(nproc)
server!max_connection_reuse = 500
server!timeout = 15
server!sendfile_min = 32768
server!sendfile_max = 2097152
# Cache settings
cache!enabled = 1
cache!max_size = 134217728
cache!max_file_size = 1048576
cache!directory = $CHEROKEE_CACHE_DIR
cache!lasting_stat = 1
cache!lasting_mmap = 1
# MIME types
mime!application/javascript!extensions = js
mime!text/css!extensions = css
mime!text/html!extensions = html,htm
mime!image/png!extensions = png
mime!image/jpeg!extensions = jpg,jpeg
mime!image/gif!extensions = gif
# Virtual server
vserver!1!nick = default
vserver!1!document_root = /var/www/html
vserver!1!directory_index = index.html,index.htm
# Static file rules with caching
vserver!1!rule!100!match = extensions
vserver!1!rule!100!match!extensions = css,js,png,jpg,jpeg,gif,ico,pdf
vserver!1!rule!100!handler = file
vserver!1!rule!100!handler!iocache = 1
vserver!1!rule!100!expiration = 2592000
# Compression rules
vserver!1!rule!200!match = extensions
vserver!1!rule!200!match!extensions = html,htm,css,js,xml,txt,json,svg
vserver!1!rule!200!handler = file
vserver!1!rule!200!encoder!gzip = 1
vserver!1!rule!200!encoder!gzip!compression_level = 6
# Default rule
vserver!1!rule!500!match = default
vserver!1!rule!500!handler = file
# Admin interface
admin!enabled = 1
admin!port = $ADMIN_PORT
admin!ssl = 0
EOF
chmod 644 "$CHEROKEE_CONFIG"
chown root:root "$CHEROKEE_CONFIG"
}
# Enable and start Cherokee service
setup_service() {
print_status "[6/8] Enabling and starting Cherokee service..."
systemctl enable cherokee
systemctl start cherokee
# Verify service is running
if ! systemctl is-active --quiet cherokee; then
print_error "Cherokee service failed to start"
systemctl status cherokee
exit 1
fi
}
# Configure firewall
setup_firewall() {
print_status "[7/8] Configuring firewall..."
# Configure firewall for HTTP and admin ports
if command -v ufw &> /dev/null; then
# Ubuntu/Debian UFW
ufw allow 80/tcp comment "Cherokee HTTP"
ufw allow "$ADMIN_PORT"/tcp comment "Cherokee Admin"
elif command -v firewall-cmd &> /dev/null; then
# RHEL-based firewalld
firewall-cmd --permanent --add-port=80/tcp
firewall-cmd --permanent --add-port="$ADMIN_PORT"/tcp
firewall-cmd --reload
fi
}
# Verify installation
verify_installation() {
print_status "[8/8] Verifying installation..."
# Check if Cherokee is running
if ! systemctl is-active --quiet cherokee; then
print_error "Cherokee service is not running"
return 1
fi
# Check if cache directory exists and has correct permissions
if [[ ! -d "$CHEROKEE_CACHE_DIR" ]]; then
print_error "Cache directory not found"
return 1
fi
# Check if port 80 is listening
if ! netstat -tln 2>/dev/null | grep -q ":80 " && ! ss -tln 2>/dev/null | grep -q ":80 "; then
print_warning "Cherokee may not be listening on port 80"
fi
# Check if admin port is listening
if ! netstat -tln 2>/dev/null | grep -q ":$ADMIN_PORT " && ! ss -tln 2>/dev/null | grep -q ":$ADMIN_PORT "; then
print_warning "Cherokee admin interface may not be accessible"
fi
print_status "Cherokee installation completed successfully!"
print_status "Web server: http://$(hostname -I | awk '{print $1}')"
print_status "Admin interface: http://$(hostname -I | awk '{print $1}'):$ADMIN_PORT"
print_status "Cache directory: $CHEROKEE_CACHE_DIR"
print_status "Configuration file: $CHEROKEE_CONFIG"
print_warning "Remember to secure the admin interface in production!"
}
# Main execution
main() {
print_status "Starting Cherokee installation with caching and compression..."
check_privileges
detect_distro
update_system
install_cherokee
setup_user
setup_cache_directory
configure_cherokee
setup_service
setup_firewall
verify_installation
print_status "Installation completed successfully!"
}
# Run main function
main "$@"
Review the script before running. Execute with: bash install.sh