Web Server Configuration

This guide covers configuring NGINX to serve your PteroCA installation.

Prerequisites

• NGINX installed on your system

• PteroCA files installed in /var/www/pteroca

• PHP-FPM installed and running

• Domain name or IP address for your panel

Create NGINX Configuration

Create the configuration file pteroca.conf and place it in /etc/nginx/sites-available/.

cd /etc/nginx/sites-available/
sudo nano pteroca.conf

Example NGINX Configuration

server {
    listen 80;
    root /var/www/pteroca/public;
    index index.php index.html index.htm;
    server_name YOUR.DOMAIN.COM;

    location / {
        try_files $uri $uri/ /index.php?$query_string;
    }

    location ~ \.php$ {
        include snippets/fastcgi-php.conf;
        fastcgi_pass unix:/var/run/php/php8.2-fpm.sock;
    }

    location ~ /\.ht {
        deny all;
    }
}

Configuration Notes

PHP Version

The provided configuration uses php8.2-fpm.sock. If you are using a different PHP version (e.g., PHP 8.3), make sure to update the fastcgi_pass directive accordingly:

fastcgi_pass unix:/var/run/php/php8.3-fpm.sock;

Important: Failure to adjust this may result in NGINX not starting correctly.

Domain Name

Replace YOUR.DOMAIN.COM with your actual domain name. If you are using this configuration for local development, you can use a placeholder like localhost or a custom local domain.

Enable Configuration

After creating your configuration file, enable it and restart NGINX.

# Enable NGINX configuration
sudo ln -s /etc/nginx/sites-available/pteroca.conf /etc/nginx/sites-enabled/pteroca.conf

# Check for errors in NGINX configuration
sudo nginx -t

# Restart NGINX to apply changes
sudo systemctl restart nginx

Verify Configuration

Test NGINX Syntax

Before restarting, always test the configuration:

sudo nginx -t

You should see:

nginx: the configuration file /etc/nginx/nginx.conf syntax is ok
nginx: configuration file /etc/nginx/nginx.conf test is successful

Check NGINX Status

sudo systemctl status nginx

Test in Browser

Visit your domain or IP address in a web browser. You should see the PteroCA interface (or installation page if not yet configured).

Adding SSL with Certbot

For production environments, you should always use SSL/HTTPS. The easiest way is using Certbot from Let's Encrypt.

Install Certbot

sudo apt update
sudo apt install -y certbot python3-certbot-nginx

Obtain SSL Certificate

sudo certbot --nginx -d yourdomain.com

Certbot will:

1. Automatically modify your NGINX configuration

2. Obtain and install SSL certificates

3. Set up automatic certificate renewal

4. Redirect HTTP to HTTPS

Verify Auto-Renewal

Certbot sets up automatic renewal. Test the renewal process:

sudo certbot renew --dry-run

NGINX Configuration After SSL

After running Certbot, your configuration will be automatically updated to something like:

server {
    root /var/www/pteroca/public;
    index index.php index.html index.htm;
    server_name yourdomain.com;

    location / {
        try_files $uri $uri/ /index.php?$query_string;
    }

    location ~ \.php$ {
        include snippets/fastcgi-php.conf;
        fastcgi_pass unix:/var/run/php/php8.2-fpm.sock;
    }

    location ~ /\.ht {
        deny all;
    }

    listen 443 ssl; # managed by Certbot
    ssl_certificate /etc/letsencrypt/live/yourdomain.com/fullchain.pem; # managed by Certbot
    ssl_certificate_key /etc/letsencrypt/live/yourdomain.com/privkey.pem; # managed by Certbot
    include /etc/letsencrypt/options-ssl-nginx.conf; # managed by Certbot
    ssl_dhparam /etc/letsencrypt/ssl-dhparams.pem; # managed by Certbot
}

server {
    if ($host = yourdomain.com) {
        return 301 https://$host$request_uri;
    } # managed by Certbot

    listen 80;
    server_name yourdomain.com;
    return 404; # managed by Certbot
}

Troubleshooting

NGINX Won't Start

Check error logs:

sudo tail -f /var/log/nginx/error.log

Common issues:

• Wrong PHP-FPM socket path

• Syntax errors in configuration

• Port 80/443 already in use

• Invalid domain name

502 Bad Gateway

Possible causes:

1. PHP-FPM not running:

   sudo systemctl status php8.2-fpm
   sudo systemctl start php8.2-fpm

2. Wrong socket path in configuration

3. PHP-FPM socket permissions

403 Forbidden

Possible causes:

1. Wrong document root path

2. File permissions:

   sudo chown -R www-data:www-data /var/www/pteroca
   sudo chmod -R 755 /var/www/pteroca

3. Missing index file

404 Not Found

Possible causes:

1. try_files directive incorrect

2. Rewrite rules not working

3. Wrong root directory

Performance Optimization

Enable Gzip Compression

Add to your NGINX configuration:

gzip on;
gzip_vary on;
gzip_proxied any;
gzip_comp_level 6;
gzip_types text/plain text/css text/xml text/javascript application/json application/javascript application/xml+rss;

Browser Caching

Add caching headers for static assets:

location ~* \.(jpg|jpeg|png|gif|ico|css|js|svg|woff|woff2|ttf|eot)$ {
    expires 1y;
    add_header Cache-Control "public, immutable";
}

Client Body Size

Increase upload limits if needed:

client_max_body_size 100M;

Security Hardening

Hide NGINX Version

Add to http block in /etc/nginx/nginx.conf:

server_tokens off;

Add Security Headers

add_header X-Frame-Options "SAMEORIGIN" always;
add_header X-Content-Type-Options "nosniff" always;
add_header X-XSS-Protection "1; mode=block" always;
add_header Referrer-Policy "no-referrer-when-downgrade" always;

Next Steps

After configuring the web server:

1. Configure CSRF and Trusted Proxies - If using Cloudflare or reverse proxy

2. Configure Database - Set up MySQL/MariaDB connection

3. Configure System - Complete system setup

Web server configuration issues? Check the troubleshooting guide or ask in our Discord community.

Related Guides

• Manual Installation - Complete installation guide

• SSL Configuration - Advanced SSL setup

• Troubleshooting - Common issues and solutions