Web Server Setup

Proper web server configuration is critically important for Flute CMS operation. This guide covers setting up the most popular web servers: Apache, Nginx, and Lighttpd.

⚠️

Make sure your server meets the minimum requirements before starting configuration.

General Requirements

Document Root

The web server’s document root should point to the public folder of your Flute CMS installation, not the root folder of the project.

Correct structure:


/var/www/html/
├── app/
├── config/
├── public/          ← Document root should point here
│   ├── index.php
│   └── .htaccess
├── storage/
└── vendor/

URL Rewriting

Flute CMS requires URL rewriting support to work correctly. All requests should be redirected to public/index.php.

PHP Configuration

Make sure the following PHP extensions are enabled:

PDO
GD
BCMath
JSON
Mbstring
SimpleXML
Zip
Curl
GMP

Apache Configuration

Apache is the most popular web server and usually requires minimal configuration.

Virtual Host

Virtual Host Configuration

Create a virtual host configuration file:


<VirtualHost *:80>
    ServerName yoursite.com
    ServerAlias www.yoursite.com
    DocumentRoot /var/www/html/yoursite/public
    
    <Directory /var/www/html/yoursite/public>
        AllowOverride All
        Require all granted
        
        # Enable URL rewriting
        RewriteEngine On
        
        # Redirect to HTTPS (optional)
        RewriteCond %{HTTPS} off
        RewriteRule ^(.*)$ https://%{HTTP_HOST}%{REQUEST_URI} [L,R=301]
    </Directory>
    
    # Logs
    ErrorLog ${APACHE_LOG_DIR}/yoursite_error.log
    CustomLog ${APACHE_LOG_DIR}/yoursite_access.log combined
</VirtualHost>
 
<VirtualHost *:443>
    ServerName yoursite.com
    ServerAlias www.yoursite.com
    DocumentRoot /var/www/html/yoursite/public
    
    # SSL Configuration
    SSLEngine on
    SSLCertificateFile /path/to/certificate.crt
    SSLCertificateKeyFile /path/to/private.key
    
    <Directory /var/www/html/yoursite/public>
        AllowOverride All
        Require all granted
    </Directory>
    
    # Logs
    ErrorLog ${APACHE_LOG_DIR}/yoursite_ssl_error.log
    CustomLog ${APACHE_LOG_DIR}/yoursite_ssl_access.log combined
</VirtualHost>

Enable the site:


sudo a2ensite yoursite.conf
sudo systemctl reload apache2

Shared Hosting

On shared hosting, you usually can’t modify virtual host configuration. Use .htaccess file in the public folder:


# public/.htaccess
RewriteEngine On
 
# Handle Angular and Vue.js routes
RewriteCond %{REQUEST_FILENAME} !-f
RewriteCond %{REQUEST_FILENAME} !-d
RewriteRule ^(.*)$ index.php [QSA,L]
 
# Security headers
Header always set X-Content-Type-Options nosniff
Header always set X-Frame-Options DENY
Header always set X-XSS-Protection "1; mode=block"
 
# Cache static files
<IfModule mod_expires.c>
    ExpiresActive On
    ExpiresByType text/css "access plus 1 month"
    ExpiresByType application/javascript "access plus 1 month"
    ExpiresByType image/png "access plus 1 month"
    ExpiresByType image/jpg "access plus 1 month"
    ExpiresByType image/jpeg "access plus 1 month"
    ExpiresByType image/gif "access plus 1 month"
    ExpiresByType image/svg+xml "access plus 1 month"
</IfModule>
 
# Gzip compression
<IfModule mod_deflate.c>
    AddOutputFilterByType DEFLATE text/plain
    AddOutputFilterByType DEFLATE text/html
    AddOutputFilterByType DEFLATE text/xml
    AddOutputFilterByType DEFLATE text/css
    AddOutputFilterByType DEFLATE application/xml
    AddOutputFilterByType DEFLATE application/xhtml+xml
    AddOutputFilterByType DEFLATE application/rss+xml
    AddOutputFilterByType DEFLATE application/javascript
    AddOutputFilterByType DEFLATE application/x-javascript
</IfModule>

If the site is in a subdirectory:


# For installation in subdirectory like yoursite.com/flute/
RewriteBase /flute/
RewriteRule ^(.*)$ index.php [QSA,L]

Subdirectory

Subdirectory Installation

If Flute CMS is installed in a subdirectory (e.g., yoursite.com/cms/):


Alias /cms /var/www/html/flute/public
 
<Directory /var/www/html/flute/public>
    AllowOverride All
    Require all granted
    
    RewriteEngine On
    RewriteBase /cms/
    RewriteCond %{REQUEST_FILENAME} !-f
    RewriteCond %{REQUEST_FILENAME} !-d
    RewriteRule ^(.*)$ index.php [QSA,L]
</Directory>

Nginx Configuration

Nginx requires manual configuration as it doesn’t support .htaccess files.

Basic Configuration

Basic Nginx Configuration


server {
    listen 80;
    server_name yoursite.com www.yoursite.com;
    root /var/www/html/yoursite/public;
    index index.php index.html;
    
    # Security headers
    add_header X-Frame-Options "SAMEORIGIN" always;
    add_header X-XSS-Protection "1; mode=block" always;
    add_header X-Content-Type-Options "nosniff" always;
    add_header Referrer-Policy "no-referrer-when-downgrade" always;
    add_header Content-Security-Policy "default-src 'self' http: https: data: blob: 'unsafe-inline'" always;
    
    # Main location
    location / {
        try_files $uri $uri/ /index.php?$query_string;
    }
    
    # PHP processing
    location ~ \.php$ {
        fastcgi_pass unix:/var/run/php/php8.2-fpm.sock;
        fastcgi_param SCRIPT_FILENAME $realpath_root$fastcgi_script_name;
        include fastcgi_params;
        fastcgi_hide_header X-Powered-By;
    }
    
    # Deny access to sensitive files
    location ~ /\. {
        deny all;
    }
    
    location ~ /(storage|config|app)/ {
        deny all;
    }
    
    # Static files caching
    location ~* \.(css|js|png|jpg|jpeg|gif|ico|svg|woff|woff2|ttf|eot)$ {
        expires 1M;
        add_header Cache-Control "public, immutable";
    }
}

With SSL

Configuration with SSL


# Redirect HTTP to HTTPS
server {
    listen 80;
    server_name yoursite.com www.yoursite.com;
    return 301 https://$server_name$request_uri;
}
 
# HTTPS configuration
server {
    listen 443 ssl http2;
    server_name yoursite.com www.yoursite.com;
    root /var/www/html/yoursite/public;
    index index.php index.html;
    
    # SSL Configuration
    ssl_certificate /path/to/certificate.crt;
    ssl_certificate_key /path/to/private.key;
    ssl_protocols TLSv1.2 TLSv1.3;
    ssl_ciphers ECDHE-RSA-AES256-GCM-SHA512:DHE-RSA-AES256-GCM-SHA512:ECDHE-RSA-AES256-GCM-SHA384:DHE-RSA-AES256-GCM-SHA384;
    ssl_prefer_server_ciphers off;
    ssl_session_cache shared:SSL:10m;
    ssl_session_timeout 10m;
    
    # Security headers
    add_header Strict-Transport-Security "max-age=31536000; includeSubDomains" always;
    add_header X-Frame-Options "SAMEORIGIN" always;
    add_header X-XSS-Protection "1; mode=block" always;
    add_header X-Content-Type-Options "nosniff" always;
    
    # Main location
    location / {
        try_files $uri $uri/ /index.php?$query_string;
    }
    
    # PHP processing
    location ~ \.php$ {
        fastcgi_pass unix:/var/run/php/php8.2-fpm.sock;
        fastcgi_param SCRIPT_FILENAME $realpath_root$fastcgi_script_name;
        include fastcgi_params;
        fastcgi_hide_header X-Powered-By;
        
        # Security
        fastcgi_param HTTP_PROXY "";
    }
    
    # Deny access to sensitive files
    location ~ /\. {
        deny all;
    }
    
    location ~ /(storage|config|app)/ {
        deny all;
    }
}

Performance Optimized

Performance Optimized Configuration


server {
    listen 443 ssl http2;
    server_name yoursite.com;
    root /var/www/html/yoursite/public;
    index index.php;
    
    # SSL Configuration (same as above)
    ssl_certificate /path/to/certificate.crt;
    ssl_certificate_key /path/to/private.key;
    
    # Gzip compression
    gzip on;
    gzip_vary on;
    gzip_min_length 1024;
    gzip_proxied any;
    gzip_comp_level 6;
    gzip_types
        text/plain
        text/css
        text/xml
        text/javascript
        application/json
        application/javascript
        application/xml+rss
        application/atom+xml
        image/svg+xml;
    
    # Main location with caching
    location / {
        try_files $uri $uri/ /index.php?$query_string;
        
        # Cache static content
        location ~* \.(css|js|png|jpg|jpeg|gif|ico|svg|woff|woff2|ttf|eot)$ {
            expires 1y;
            add_header Cache-Control "public, immutable";
            access_log off;
        }
    }
    
    # PHP processing with caching
    location ~ \.php$ {
        fastcgi_pass unix:/var/run/php/php8.2-fpm.sock;
        fastcgi_param SCRIPT_FILENAME $realpath_root$fastcgi_script_name;
        include fastcgi_params;
        
        # FastCGI caching
        fastcgi_cache_valid 200 1h;
        fastcgi_cache_use_stale error timeout invalid_header updating http_500;
        fastcgi_cache_background_update on;
        fastcgi_cache_lock on;
    }
    
    # Security
    location ~ /\. {
        deny all;
    }
    
    location ~ /(storage|config|app|vendor)/ {
        deny all;
    }
}

Lighttpd Configuration

Lighttpd is a lightweight web server suitable for high-load sites.


# /etc/lighttpd/conf-available/yoursite.conf

$HTTP["host"] == "yoursite.com" {
    server.document-root = "/var/www/html/yoursite/public"
    
    # URL rewriting
    url.rewrite-if-not-file = (
        "^/(.*)$" => "/index.php/$1"
    )
    
    # PHP FastCGI
    fastcgi.server = ( ".php" =>
        ((
            "bin-path" => "/usr/bin/php-cgi",
            "socket" => "/tmp/php.socket",
            "max-procs" => 2,
            "idle-timeout" => 20,
            "bin-environment" => (
                "PHP_FCGI_CHILDREN" => "4",
                "PHP_FCGI_MAX_REQUESTS" => "10000"
            ),
            "bin-copy-environment" => (
                "PATH", "SHELL", "USER"
            ),
            "broken-scriptfilename" => "enable"
        ))
    )
    
    # Security
    $HTTP["url"] =~ "^/(storage|config|app)/" {
        url.access-deny = ( "" )
    }
    
    # Static file caching
    $HTTP["url"] =~ "\.(css|js|png|jpg|jpeg|gif|ico|svg|woff|woff2|ttf|eot)$" {
        expire.url = ( "" => "access plus 1 months" )
    }
}

Troubleshooting

404 Error on All Pages

Cause: URL rewriting not working.

Solution:

Apache: Make sure mod_rewrite is enabled and AllowOverride All is set
Nginx: Check that try_files directive is configured correctly
Lighttpd: Verify url.rewrite-if-not-file configuration

500 Internal Server Error

Cause: PHP errors or incorrect permissions.

Solution:

Check web server error logs
Enable PHP error display in config/app.php
Check file permissions (755 for folders, 644 for files)
Make sure storage/ folder is writable

Static Files Not Loading

Cause: Incorrect document root or security restrictions.

Solution:

Make sure document root points to public/ folder
Check that static files exist in public/ folder
Verify there are no security rules blocking access to static files

Performance Issues

Solutions:

Enable caching: Configure browser caching for static files
Enable compression: Use Gzip/Brotli compression
Optimize PHP: Enable OPcache and configure PHP-FPM
Use CDN: For static content delivery

After configuring the web server, test your site thoroughly and check that all functions work correctly.