Troubleshooting — NGINX

Overview

NGINX serves as the reverse proxy and web server for the Diskover platform. It handles all incoming HTTP/HTTPS traffic and routes it to the appropriate backend:

diskover-web (PHP) — served via FastCGI to PHP-FPM on port 8000
diskover-admin (Python/Flask) — proxied to a Unix socket or upstream HTTP port

All client traffic enters through NGINX. Neither PHP-FPM nor the diskover-admin uvicorn process are exposed directly.

Service Management

RHEL / CentOS / Rocky Linux

# Start
sudo systemctl start nginx

# Stop
sudo systemctl stop nginx

# Restart
sudo systemctl restart nginx

# Reload config without dropping connections
sudo systemctl reload nginx

# Status
sudo systemctl status nginx

# Enable on boot
sudo systemctl enable nginx

Ubuntu / Debian

# Start
sudo systemctl start nginx

# Stop
sudo systemctl stop nginx

# Restart
sudo systemctl restart nginx

# Reload config without dropping connections
sudo systemctl reload nginx

# Status
sudo systemctl status nginx

# Enable on boot
sudo systemctl enable nginx

Note: Use reload rather than restart when making config changes — it applies the new configuration without dropping active connections.

Test Config Before Applying

Always validate the NGINX configuration before reloading:

sudo nginx -t

A valid config returns:

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

Configuration

File Locations

File	Purpose
`/etc/nginx/nginx.conf`	Main NGINX config (worker processes, logging, includes)
`/etc/nginx/conf.d/diskover-web.conf`	Diskover virtual host — server blocks and proxy rules
`/etc/nginx/proxy_params`	Shared proxy headers included by location blocks

diskover-web.conf — Bare Metal

On bare metal installations, diskover-admin is proxied via a Unix socket:

server {
    listen 8000 default_server;
    listen [::]:8000 default_server;
    server_name _;

    root /var/www/diskover-web/public;
    index index.php index.html index.htm;

    # diskover-web PHP application
    location / {
        try_files $uri $uri/ /index.php$is_args$args;
    }

    location ~ \.(php|phar)(/.*)?$ {
        fastcgi_split_path_info ^(.+\.(?:php|phar))(/.*)$;
        fastcgi_intercept_errors on;
        fastcgi_index  index.php;
        include        fastcgi_params;
        fastcgi_param  SCRIPT_FILENAME  $document_root$fastcgi_script_name;
        fastcgi_param  PATH_INFO $fastcgi_path_info;
        fastcgi_pass   127.0.0.1:9000;
    }

    # diskover-admin reverse proxy (Unix socket)
    location /diskover_admin {
        include proxy_params;
        proxy_pass http://unix:/var/www/diskover-admin/run/diskover-admin.sock;
    }

    # Block .htaccess access
    location ~ /\.ht {
        deny all;
    }
}

proxy_params

proxy_set_header Host $http_host;
proxy_set_header X-Real-IP $remote_addr;
proxy_set_header X-Forwarded-For $proxy_add_x_forwarded_for;
proxy_set_header X-Forwarded-Proto $scheme;

HTTPS / SSL Configuration

Add an HTTPS server block to diskover-web.conf:

server {
    listen 443 ssl default_server;
    listen [::]:443 ssl default_server;
    server_name _;

    root /var/www/diskover-web/public;
    index index.php index.html index.htm;

    ssl_certificate     /etc/nginx/ssl/certificate.crt;
    ssl_certificate_key /etc/nginx/ssl/privatekey.key;
    ssl_session_cache   shared:SSL:1m;
    ssl_session_timeout 10m;
    ssl_protocols       TLSv1.2 TLSv1.3;
    ssl_ciphers         HIGH:!aNULL:!MD5;
    ssl_prefer_server_ciphers on;

    # Same location blocks as HTTP server block above
    location / {
        try_files $uri $uri/ /index.php$is_args$args;
    }

    location ~ \.(php|phar)(/.*)?$ {
        fastcgi_split_path_info ^(.+\.(?:php|phar))(/.*)$;
        fastcgi_intercept_errors on;
        fastcgi_index  index.php;
        include        fastcgi_params;
        fastcgi_param  SCRIPT_FILENAME  $document_root$fastcgi_script_name;
        fastcgi_param  PATH_INFO $fastcgi_path_info;
        fastcgi_pass   127.0.0.1:9000;
    }

    location /diskover_admin {
        include proxy_params;
        proxy_pass http://unix:/var/www/diskover-admin/run/diskover-admin.sock;
    }

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

Place SSL certificates at:

Certificate: /etc/nginx/ssl/certificate.crt
Private key: /etc/nginx/ssl/privatekey.key

sudo mkdir -p /etc/nginx/ssl
sudo chmod 700 /etc/nginx/ssl

Note: TLSv1 and TLSv1.1 are deprecated and should not be included in ssl_protocols. Use TLSv1.2 and TLSv1.3 only.

Redirect HTTP to HTTPS

To force all traffic over HTTPS, replace the HTTP server block with a redirect:

server {
    listen 8000 default_server;
    listen [::]:8000 default_server;
    server_name _;
    return 301 https://$host$request_uri;
}

Log Locations

Log	Default Path
Error log	`/var/log/nginx/error.log`
Access log	`/var/log/nginx/access.log`

Tail logs:

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

Log paths can be customised in /etc/nginx/nginx.conf:

error_log  /var/log/nginx/error.log notice;
access_log /var/log/nginx/access.log combined;

Common Operations

Check Which Config File NGINX Is Using

sudo nginx -V 2>&1 | grep -o '\-\-conf-path=[^ ]*'

View Active Connections

# Requires nginx stub_status module
curl http://localhost/nginx_status

Reload After Certificate Renewal

After renewing SSL certificates, reload NGINX to pick up the new files without dropping connections:

sudo systemctl reload nginx

Check Socket File (Bare Metal)

The diskover-admin Unix socket must exist and be accessible to NGINX before NGINX can proxy requests to it:

ls -la /var/www/diskover-admin/run/diskover-admin.sock

Expected output: socket file owned by nginx:nginx with permissions 777. If the socket is missing, diskover-admin is not running — see the diskover-admin doc.

Fix Socket Permissions Manually

If NGINX returns 502 and the socket exists but has wrong permissions:

sudo chown nginx:nginx /var/www/diskover-admin/run/diskover-admin.sock
sudo chmod 777 /var/www/diskover-admin/run/diskover-admin.sock

Troubleshooting

502 Bad Gateway on /diskover_admin

NGINX can reach diskover-web (PHP) but cannot proxy to diskover-admin.

Check that diskover-admin is running:

sudo systemctl status diskover-admin

Check that the socket exists:

ls -la /var/www/diskover-admin/run/diskover-admin.sock

If the socket is missing, start diskover-admin:

sudo systemctl start diskover-admin

If the socket exists but 502 persists, check permissions (see above) and check for errors in the diskover-admin logs.

403 Forbidden

Check file ownership on the web root:

ls -la /var/www/diskover-web/public

The NGINX worker user (nginx on RHEL/Rocky, www-data on Ubuntu) must be able to read the files:

# RHEL / Rocky
sudo chown -R nginx:nginx /var/www/diskover-web

# Ubuntu
sudo chown -R www-data:www-data /var/www/diskover-web

Check SELinux (RHEL/Rocky):

sudo ausearch -m avc -ts recent | grep nginx

If SELinux is blocking access:

# Allow nginx to serve files from the web root
sudo chcon -Rt httpd_sys_content_t /var/www/diskover-web

# Allow nginx to connect to network sockets (for proxy)
sudo setsebool -P httpd_can_network_connect 1

nginx Won't Start — Port Already in Use

sudo ss -tlnp | grep ':80\|:443'

If another process is on port 80 or 443, either stop it or change NGINX’s listen port in diskover-web.conf.

PHP Pages Return Blank or 500 Error

Check PHP-FPM is running:

# RHEL / Rocky
sudo systemctl status php-fpm

# Ubuntu (version may vary)
sudo systemctl status php8.2-fpm

Check NGINX error log for FastCGI errors:

sudo tail -50 /var/log/nginx/error.log | grep fastcgi

Common fix — PHP-FPM socket/port mismatch: Ensure the fastcgi_pass directive in diskover-web.conf matches PHP-FPM's configured listen address. Check /etc/php-fpm.d/www.conf (RHEL) or /etc/php/*/fpm/pool.d/www.conf (Ubuntu) for the listen = value.

SSL Certificate Errors in Browser

Check certificate validity:

sudo openssl x509 -in /etc/nginx/ssl/certificate.crt -noout -dates -subject

Check NGINX can read the certificate and key:

sudo nginx -t

If NGINX reports cannot load certificate or cannot load private key, check file paths and permissions:

sudo ls -la /etc/nginx/ssl/
sudo chmod 600 /etc/nginx/ssl/privatekey.key
sudo chmod 644 /etc/nginx/ssl/certificate.crt

Official Documentation