Skip to main content

Nginx

Purpose​

This page documents how Nginx is used in Maqsafy as a web server and reverse proxy for backend, frontend, dashboard, and API services.

Nginx Responsibilities​

Nginx may be responsible for:

  • Receiving HTTP/HTTPS requests
  • Routing requests to backend services
  • Serving frontend applications
  • Acting as a reverse proxy
  • Handling SSL/TLS termination
  • Managing redirects
  • Enforcing request size limits
  • Serving static files
  • Logging access and error events

Common Reverse Proxy Flow​

Client Browser / Mobile App
        ↓
Nginx
        ↓
Backend / Frontend / Dashboard Service
        ↓
Database / Redis / External Integrations

Common Commands​

Validate Nginx configuration:

sudo nginx -t

Reload Nginx after a valid configuration change:

sudo systemctl reload nginx

Restart Nginx:

sudo systemctl restart nginx

Check Nginx status:

sudo systemctl status nginx

View error logs:

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

View access logs:

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

Example Server Block​

Use placeholders only.

server {
    listen 80;
    server_name example.com;

    location / {
        proxy_pass http://127.0.0.1:3000;
        proxy_set_header Host $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;
    }
}

API Reverse Proxy Example​

server {
    listen 443 ssl;
    server_name api.example.com;

    ssl_certificate /path/to/fullchain.pem;
    ssl_certificate_key /path/to/privkey.pem;

    location / {
        proxy_pass http://127.0.0.1:3002;
        proxy_set_header Host $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;
    }
}

Common Issues​

502 Bad Gateway​

Possible causes:

  • Upstream service is down.
  • Nginx is pointing to the wrong port.
  • Docker container is not running.
  • Backend service is unhealthy.
  • Firewall or network restriction.

Diagnostic commands:

sudo nginx -t
sudo tail -f /var/log/nginx/error.log
docker ps
docker logs <container-name>

413 Payload Too Large​

Possible cause:

  • Request body size exceeds Nginx limit.

Possible configuration:

client_max_body_size 20M;

Redirect Loop​

Possible causes:

  • Incorrect proxy headers.
  • SSL termination mismatch.
  • Application URL configuration mismatch.
  • Cloudflare or external proxy SSL mode mismatch.

SSL/TLS Notes​

  • Production traffic should use HTTPS.
  • SSL certificates must be renewed before expiry.
  • TLS configuration should be reviewed periodically.
  • Private key paths must not be exposed in public documentation.

Security Headers​

Document only if configured.

Example placeholders:

add_header X-Frame-Options "SAMEORIGIN";
add_header X-Content-Type-Options "nosniff";
add_header Referrer-Policy "strict-origin-when-cross-origin";

Operational Rules​

  • Always run sudo nginx -t before reloading Nginx.
  • Do not reload Nginx with invalid configuration.
  • Do not document private SSL keys.
  • Do not expose internal upstream IPs if not needed.
  • Use placeholders for domains, paths, and ports.