Set up Cherokee web server with web-based administration, FastCGI support for PHP applications, SSL-enabled virtual hosts, and performance optimizations for lightweight web hosting environments.
Prerequisites
- Root or sudo access
- Domain names pointing to your server
- Basic understanding of web server concepts
What this solves
Cherokee is a lightweight, high-performance web server that provides an intuitive web-based administration interface and excellent FastCGI support. This tutorial walks you through installing Cherokee, configuring it with the cherokee-admin interface, setting up SSL-enabled virtual hosts, and optimizing it for PHP applications with FastCGI.
Step-by-step installation
Update system packages
Start by updating your package manager to ensure you get the latest versions available.
sudo apt update && sudo apt upgrade -y
Install Cherokee web server
Install Cherokee and its PHP FastCGI module. Cherokee provides excellent FastCGI support out of the box.
sudo apt install -y cherokee php-fpm php-cli php-mysql php-curl php-gd php-xml
Configure PHP-FPM
Configure PHP-FPM to work with Cherokee by ensuring it listens on a Unix socket for better performance.
listen = /var/run/php/php8.3-fpm.sock
listen.owner = www-data
listen.group = www-data
listen.mode = 0660
pm.max_children = 50
pm.start_servers = 5
pm.min_spare_servers = 5
pm.max_spare_servers = 35
Start and enable services
Enable Cherokee and PHP-FPM services to start automatically on boot.
sudo systemctl enable --now cherokee
sudo systemctl enable --now php8.3-fpm
sudo systemctl status cherokee
sudo systemctl status php8.3-fpm
Configure firewall access
Open the necessary ports for HTTP, HTTPS, and Cherokee admin interface access.
sudo ufw allow 80/tcp
sudo ufw allow 443/tcp
sudo ufw allow 9090/tcp
Configure Cherokee admin interface
Launch Cherokee admin
Start the Cherokee admin interface to configure your web server through the web-based interface.
sudo cherokee-admin -b -t 60
Access admin interface
Open your web browser and navigate to the admin interface. Cherokee admin will display the access URL and one-time password.
http://your-server-ip:9090
Configure basic settings
In the Cherokee admin interface, configure the basic server settings including server name and administrator email.
- Navigate to "General" in the admin interface
- Set your server name to your domain (example.com)
- Configure the administrator email
- Set the server timeout to 60 seconds
Set up virtual hosts
Create directory structure
Create directories for your virtual host websites with proper ownership and permissions.
sudo mkdir -p /var/www/example.com/public_html
sudo mkdir -p /var/www/test.example.com/public_html
sudo chown -R www-data:www-data /var/www/
sudo chmod -R 755 /var/www/
Create test pages
Create simple test pages to verify your virtual host configuration works correctly.
<?php
echo "<h1>Welcome to example.com</h1>";
echo "<p>Server: " . $_SERVER['SERVER_NAME'] . "</p>";
echo "<p>PHP Version: " . phpversion() . "</p>";
?>
<?php
echo "<h1>Welcome to test.example.com</h1>";
echo "<p>Server: " . $_SERVER['SERVER_NAME'] . "</p>";
echo "<p>PHP Version: " . phpversion() . "</p>";
?>
Configure virtual hosts in Cherokee admin
Use the Cherokee admin interface to create and configure virtual hosts with FastCGI support.
- In Cherokee admin, go to "Virtual Servers"
- Click "Add new Virtual Server"
- Set the nickname to "example.com"
- Set document root to "/var/www/example.com/public_html"
- In "Host Match", add "example.com" and "www.example.com"
- Repeat for test.example.com
Configure PHP FastCGI handler
Set up PHP processing through FastCGI for each virtual host in the Cherokee admin interface.
- Select your virtual host in Cherokee admin
- Go to "Behavior" tab
- Click "Add new rule"
- Select "Extensions" and add "php"
- Set handler to "FastCGI"
- Configure FastCGI source to use Unix socket: "/var/run/php/php8.3-fpm.sock"
- Click "Add" to create the information source if needed
Configure SSL certificates
Install Certbot
Install Certbot to obtain free Let's Encrypt SSL certificates for your domains.
sudo apt install -y certbot
Obtain SSL certificates
Use Certbot in webroot mode to obtain SSL certificates for your domains while Cherokee is running.
sudo certbot certonly --webroot -w /var/www/example.com/public_html -d example.com -d www.example.com
sudo certbot certonly --webroot -w /var/www/test.example.com/public_html -d test.example.com
Configure SSL in Cherokee admin
Configure SSL certificates for your virtual hosts through the Cherokee admin interface.
- In Cherokee admin, select your virtual host
- Go to "Security" tab
- Enable "SSL/TLS"
- Set certificate file: "/etc/letsencrypt/live/example.com/fullchain.pem"
- Set certificate key: "/etc/letsencrypt/live/example.com/privkey.pem"
- Enable "HTTPS only" redirect if desired
- Repeat for other virtual hosts
Set up certificate renewal
Configure automatic SSL certificate renewal using systemd timer.
sudo systemctl enable certbot-renew.timer
sudo systemctl start certbot-renew.timer
sudo systemctl status certbot-renew.timer
Performance optimization
Configure Cherokee performance settings
Optimize Cherokee for better performance by adjusting connection limits and timeouts through the admin interface.
- In Cherokee admin, go to "General"
- Set "Max connection reuse" to 500
- Set "Connection timeout" to 60
- Enable "Keep alive"
- Set "Max keep alive requests" to 500
Enable compression
Enable gzip compression to reduce bandwidth usage and improve page load times.
- In Cherokee admin, go to virtual host "Advanced"
- Enable "Content Encoding"
- Select "gzip" and "deflate"
- Set compression level to 6
- Add MIME types: text/html, text/css, text/javascript, application/javascript
Configure static file caching
Set up browser caching for static files to improve performance.
- In Cherokee admin, select virtual host
- Go to "Behavior" and add new rule
- Select "Extensions" and add: css, js, png, jpg, jpeg, gif, ico
- Set handler to "Static files"
- In "Expiration", set "Time" to "1 month"
Apply configuration changes
Save and apply all Cherokee configuration changes, then restart services.
sudo systemctl restart cherokee
sudo systemctl restart php8.3-fpm
sudo systemctl status cherokee
Security hardening
Hide server information
Configure Cherokee to hide version information and server details from HTTP headers.
- In Cherokee admin, go to "General"
- Disable "Server tokens"
- Set custom "Server string" if needed
Configure security headers
Add security headers to protect against common web vulnerabilities.
- In Cherokee admin, select virtual host
- Go to "Advanced" → "Custom Headers"
- Add headers:
- X-Frame-Options: DENY
- X-Content-Type-Options: nosniff
- X-XSS-Protection: 1; mode=block
- Strict-Transport-Security: max-age=31536000; includeSubDomains
Restrict access to sensitive files
Configure Cherokee to deny access to sensitive configuration files and directories.
- In Cherokee admin, go to virtual host "Behavior"
- Add new rule with "Regular Expression"
- Pattern:
\.(conf|ini|log|sh|sql)$ - Set handler to "HTTP error" with 403 Forbidden
- Add another rule for directories like .git, .svn with same settings
Verify your setup
Test your Cherokee installation, virtual hosts, SSL certificates, and PHP functionality.
sudo systemctl status cherokee
sudo systemctl status php8.3-fpm
curl -I http://example.com
curl -I https://example.com
curl https://example.com/
ssl-cert check-ssl example.com
You can also test the configuration by visiting your domains in a web browser. You should see your PHP test pages with proper SSL certificates.
Common issues
| Symptom | Cause | Fix |
|---|---|---|
| Cherokee won't start | Port 80/443 already in use | Check with sudo netstat -tlnp | grep :80 and stop conflicting services |
| PHP files download instead of executing | FastCGI not configured properly | Verify PHP-FPM is running and FastCGI source is correctly configured in Cherokee admin |
| Permission denied errors | Wrong file ownership | Run sudo chown -R www-data:www-data /var/www/ and use chmod 755 for directories, 644 for files |
| SSL certificate errors | Certificate path incorrect | Verify paths in Cherokee admin match /etc/letsencrypt/live/domain/ |
| Virtual host not working | Host match configuration wrong | Check "Host Match" settings in Cherokee admin include all domain variants |
| Cherokee admin interface inaccessible | Firewall blocking port 9090 | Open port 9090 in firewall or use SSH tunnel: ssh -L 9090:localhost:9090 user@server |
Next steps
- Configure Linux firewall rules with fail2ban for SSH brute force protection to secure your server
- Configure Linux log rotation with logrotate for maintaining Cherokee access logs
- Configure Cherokee reverse proxy and load balancing for scaling multiple backend servers
- Monitor Cherokee performance with Grafana and Prometheus for production monitoring
- Configure Cherokee with MySQL database optimization for database-driven applications
Automated install script
Run this to automate the entire setup
#!/usr/bin/env bash
set -euo pipefail
# Cherokee Web Server Installation Script
# Installs Cherokee with FastCGI, PHP-FPM, and virtual host configuration
# Colors for output
RED='\033[0;31m'
GREEN='\033[0;32m'
YELLOW='\033[1;33m'
NC='\033[0m'
# Default values
DOMAIN="${1:-example.com}"
SUBDOMAIN="${2:-test.example.com}"
# Print usage
usage() {
echo "Usage: $0 [domain] [subdomain]"
echo "Example: $0 example.com test.example.com"
exit 1
}
# 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"
}
# Cleanup on error
cleanup() {
print_error "Installation failed. Cleaning up..."
systemctl stop cherokee php-fpm 2>/dev/null || true
exit 1
}
trap cleanup ERR
# Check if running as root or with sudo
if [[ $EUID -ne 0 ]]; then
print_error "This script must be run as root or with sudo"
exit 1
fi
# Validate domain arguments
if [[ ! "$DOMAIN" =~ ^[a-zA-Z0-9]([a-zA-Z0-9-]{0,61}[a-zA-Z0-9])?(\.[a-zA-Z0-9]([a-zA-Z0-9-]{0,61}[a-zA-Z0-9])?)*$ ]]; then
print_error "Invalid domain format: $DOMAIN"
usage
fi
# Auto-detect distribution
if [ -f /etc/os-release ]; then
. /etc/os-release
case "$ID" in
ubuntu|debian)
PKG_MGR="apt"
PKG_UPDATE="apt update && apt upgrade -y"
PKG_INSTALL="apt install -y"
PHP_FPM_SERVICE="php8.3-fpm"
PHP_FPM_SOCKET="/var/run/php/php8.3-fpm.sock"
PHP_FPM_CONFIG="/etc/php/8.3/fpm/pool.d/www.conf"
FIREWALL_CMD="ufw"
;;
almalinux|rocky|centos|rhel|ol|fedora)
PKG_MGR="dnf"
PKG_UPDATE="dnf update -y"
PKG_INSTALL="dnf install -y"
PHP_FPM_SERVICE="php-fpm"
PHP_FPM_SOCKET="/var/run/php-fpm/www.sock"
PHP_FPM_CONFIG="/etc/php-fpm.d/www.conf"
FIREWALL_CMD="firewall-cmd"
;;
amzn)
PKG_MGR="yum"
PKG_UPDATE="yum update -y"
PKG_INSTALL="yum install -y"
PHP_FPM_SERVICE="php-fpm"
PHP_FPM_SOCKET="/var/run/php-fpm/www.sock"
PHP_FPM_CONFIG="/etc/php-fpm.d/www.conf"
FIREWALL_CMD="firewall-cmd"
;;
*)
print_error "Unsupported distribution: $ID"
exit 1
;;
esac
else
print_error "Cannot detect distribution - /etc/os-release not found"
exit 1
fi
print_status "Detected distribution: $ID"
print_status "Installing Cherokee for domains: $DOMAIN, $SUBDOMAIN"
# Step 1: Update system packages
echo "[1/9] Updating system packages..."
$PKG_UPDATE
# Step 2: Install Cherokee and PHP packages
echo "[2/9] Installing Cherokee and PHP packages..."
if [[ "$ID" == "ubuntu" || "$ID" == "debian" ]]; then
$PKG_INSTALL cherokee php-fpm php-cli php-mysql php-curl php-gd php-xml
else
$PKG_INSTALL epel-release
$PKG_INSTALL cherokee php-fpm php-cli php-mysqlnd php-curl php-gd php-xml
fi
# Step 3: Configure PHP-FPM
echo "[3/9] Configuring PHP-FPM..."
if [[ "$ID" == "ubuntu" || "$ID" == "debian" ]]; then
# Create PHP-FPM socket directory
mkdir -p /var/run/php
chown www-data:www-data /var/run/php
# Configure PHP-FPM pool
cat > "$PHP_FPM_CONFIG" << EOF
[www]
user = www-data
group = www-data
listen = $PHP_FPM_SOCKET
listen.owner = www-data
listen.group = www-data
listen.mode = 0660
pm = dynamic
pm.max_children = 50
pm.start_servers = 5
pm.min_spare_servers = 5
pm.max_spare_servers = 35
pm.process_idle_timeout = 10s
pm.max_requests = 500
EOF
else
# RHEL-based systems
mkdir -p /var/run/php-fpm
chown apache:apache /var/run/php-fpm
sed -i 's/user = apache/user = cherokee/' "$PHP_FPM_CONFIG"
sed -i 's/group = apache/group = cherokee/' "$PHP_FPM_CONFIG"
sed -i "s|listen = 127.0.0.1:9000|listen = $PHP_FPM_SOCKET|" "$PHP_FPM_CONFIG"
sed -i "s/;listen.owner = nobody/listen.owner = cherokee/" "$PHP_FPM_CONFIG"
sed -i "s/;listen.group = nobody/listen.group = cherokee/" "$PHP_FPM_CONFIG"
sed -i "s/;listen.mode = 0660/listen.mode = 0660/" "$PHP_FPM_CONFIG"
fi
# Step 4: Create web directories
echo "[4/9] Creating web directories..."
mkdir -p "/var/www/$DOMAIN/public_html"
mkdir -p "/var/www/$SUBDOMAIN/public_html"
if [[ "$ID" == "ubuntu" || "$ID" == "debian" ]]; then
chown -R www-data:www-data /var/www/
else
chown -R cherokee:cherokee /var/www/
fi
chmod -R 755 /var/www/
# Step 5: Create test pages
echo "[5/9] Creating test pages..."
cat > "/var/www/$DOMAIN/public_html/index.php" << EOF
<?php
echo "<h1>Welcome to $DOMAIN</h1>";
echo "<p>Server: " . \$_SERVER['SERVER_NAME'] . "</p>";
echo "<p>PHP Version: " . phpversion() . "</p>";
echo "<p>Current Time: " . date('Y-m-d H:i:s') . "</p>";
?>
EOF
cat > "/var/www/$SUBDOMAIN/public_html/index.php" << EOF
<?php
echo "<h1>Welcome to $SUBDOMAIN</h1>";
echo "<p>Server: " . \$_SERVER['SERVER_NAME'] . "</p>";
echo "<p>PHP Version: " . phpversion() . "</p>";
echo "<p>Current Time: " . date('Y-m-d H:i:s') . "</p>";
?>
EOF
if [[ "$ID" == "ubuntu" || "$ID" == "debian" ]]; then
chown -R www-data:www-data /var/www/
else
chown -R cherokee:cherokee /var/www/
fi
chmod -R 644 /var/www/*/public_html/*.php
# Step 6: Start and enable services
echo "[6/9] Starting and enabling services..."
systemctl enable --now cherokee
systemctl enable --now "$PHP_FPM_SERVICE"
# Wait for services to start
sleep 3
# Step 7: Configure firewall
echo "[7/9] Configuring firewall..."
if [[ "$FIREWALL_CMD" == "ufw" ]]; then
if command -v ufw >/dev/null 2>&1; then
ufw --force enable
ufw allow 80/tcp
ufw allow 443/tcp
ufw allow 9090/tcp
fi
else
if command -v firewall-cmd >/dev/null 2>&1; then
systemctl enable --now firewalld
firewall-cmd --permanent --add-port=80/tcp
firewall-cmd --permanent --add-port=443/tcp
firewall-cmd --permanent --add-port=9090/tcp
firewall-cmd --reload
fi
fi
# Step 8: Basic Cherokee configuration
echo "[8/9] Configuring Cherokee basic settings..."
# Create a basic Cherokee configuration
mkdir -p /etc/cherokee/sites-available
# Step 9: Verification
echo "[9/9] Verifying installation..."
if systemctl is-active --quiet cherokee; then
print_status "Cherokee is running"
else
print_error "Cherokee is not running"
exit 1
fi
if systemctl is-active --quiet "$PHP_FPM_SERVICE"; then
print_status "PHP-FPM is running"
else
print_error "PHP-FPM is not running"
exit 1
fi
print_status "Cherokee installation completed successfully!"
print_status "Web directories created at:"
print_status " - /var/www/$DOMAIN/public_html"
print_status " - /var/www/$SUBDOMAIN/public_html"
print_status ""
print_status "To configure Cherokee admin interface, run:"
print_status " sudo cherokee-admin -b -t 60"
print_status ""
print_status "Then access the admin interface at:"
print_status " http://your-server-ip:9090"
print_status ""
print_warning "Remember to configure your DNS records to point to this server"
print_warning "Configure SSL certificates for production use"
Review the script before running. Execute with: bash install.sh