Nginx Integration - GrackerAI Portal

This comprehensive guide covers Nginx integration scenarios for GrackerAI's content marketing platform, including subpath routing and reverse proxy configuration.

Subpath Routing with Nginx Reverse Proxy

Host your GrackerAI portal at a custom subpath (e.g., /news, /portal) on your domain using Nginx as a reverse proxy for seamless integration.

Prerequisites

Nginx installed (version 1.19+ recommended)
Domain configured to point to your Nginx server
SSL certificate (optional but recommended for production)

Quick Start Configuration

Step 1: Create Nginx Configuration

Create or modify your Nginx configuration file. The location depends on your setup:

Linux: /etc/nginx/nginx.conf or /etc/nginx/conf.d/yoursite.conf
Docker: Mount your config to /etc/nginx/nginx.conf
macOS (Homebrew): /usr/local/etc/nginx/nginx.conf

Step 2: Configure Reverse Proxy

Replace the default configuration with the following script. Customize the values as indicated:

Placeholder	Description	Example
`yourdomain.com`	Your domain name	`example.com`
`/yoursubpath`	Your desired subpath	`/news`, `/portal`, `/blog`

worker_processes  1;
 
events {
    worker_connections  1024;
}
 
http {
    include       mime.types;
    default_type  application/octet-stream;
 
    sendfile        on;
    keepalive_timeout  65;
 
    # Gzip settings for improved performance
    gzip  on;
    gzip_disable "msie6";
    gzip_types text/plain text/css application/json application/javascript text/xml application/xml application/xml+rss text/javascript;
 
    server {
        listen 80;
        server_name yourdomain.com;
 
        location /yoursubpath {
            # DNS Resolver (Required for dynamic upstream resolution)
            resolver 8.8.8.8 1.1.1.1 valid=300s;
            resolver_timeout 5s;
 
            # The target backend server
            proxy_pass https://portal.pseo.one/;
 
            # Required Headers for GrackerAI
            proxy_set_header Host portal.pseo.one;
            proxy_set_header x-req-domain http://yourdomain.com/yoursubpath;
 
            # Standard Proxy Headers
            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;
 
            # TLS/SSL SNI setting (Required for HTTPS backends)
            proxy_ssl_server_name on;
            proxy_ssl_name portal.pseo.one;
            proxy_ssl_session_reuse off;
 
            # Disable automatic redirect handling
            proxy_redirect off;
        }
    }
}

Step 3: Apply Configuration

After saving your configuration, reload Nginx to apply changes:

# Test configuration syntax
nginx -t
 
# Reload Nginx (graceful restart)
nginx -s reload
 
# Or if using systemctl
sudo systemctl reload nginx

Step 4: Test Your Configuration

Once deployed, verify that your reverse proxy correctly routes requests to your GrackerAI portal:

# Test with curl
curl -I http://yourdomain.com/yoursubpath
 
# Expected: HTTP 200 OK with content from GrackerAI

Docker Deployment

For containerized deployments, use the following Docker setup:

Directory Structure

nginx/
├── conf/
│   ├── nginx.conf
│   └── mime.types
└── html/
    └── index.html (optional fallback page)

Docker Run Command

docker run -d \
  --name my-nginx \
  -p 80:80 \
  -v /path/to/nginx/conf/nginx.conf:/etc/nginx/nginx.conf:ro \
  -v /path/to/nginx/html:/usr/share/nginx/html:ro \
  nginx:latest

Docker Compose

version: '3.8'
services:
  nginx:
    image: nginx:latest
    container_name: gracker-nginx
    ports:
      - "80:80"
      - "443:443"
    volumes:
      - ./conf/nginx.conf:/etc/nginx/nginx.conf:ro
      - ./html:/usr/share/nginx/html:ro
    restart: unless-stopped

Reload Configuration in Docker

docker exec my-nginx nginx -s reload

Configuration Details

Required Headers

Header	Value	Purpose
`Host`	`portal.pseo.one`	Identifies the target host to the backend
`x-req-domain`	`http://yourdomain.com/yoursubpath`	Tells GrackerAI the origin domain for content serving

SSL/TLS Configuration

The following directives are essential for proxying to HTTPS backends:

proxy_ssl_server_name on;    # Enable SNI (Server Name Indication)
proxy_ssl_name portal.pseo.one;  # Specify the SSL hostname
proxy_ssl_session_reuse off; # Disable session reuse for stability

DNS Resolver

When using dynamic hostnames, Nginx requires a resolver:

resolver 8.8.8.8 1.1.1.1 valid=300s;
resolver_timeout 5s;

Options:

8.8.8.8 - Google DNS
1.1.1.1 - Cloudflare DNS
valid=300s - Cache DNS results for 5 minutes

HTTPS Configuration (Production)

For production deployments with SSL/TLS:

server {
    listen 80;
    server_name yourdomain.com;
    return 301 https://$server_name$request_uri;
}
 
server {
    listen 443 ssl http2;
    server_name yourdomain.com;
 
    ssl_certificate /path/to/fullchain.pem;
    ssl_certificate_key /path/to/privkey.pem;
    ssl_protocols TLSv1.2 TLSv1.3;
    ssl_ciphers ECDHE-ECDSA-AES128-GCM-SHA256:ECDHE-RSA-AES128-GCM-SHA256;
    ssl_prefer_server_ciphers off;
 
    location /yoursubpath {
        resolver 8.8.8.8 1.1.1.1 valid=300s;
        resolver_timeout 5s;
 
        proxy_pass https://portal.pseo.one/;
 
        proxy_set_header Host portal.pseo.one;
        proxy_set_header x-req-domain https://yourdomain.com/yoursubpath;
 
        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;
 
        proxy_ssl_server_name on;
        proxy_ssl_name portal.pseo.one;
        proxy_ssl_session_reuse off;
 
        proxy_redirect off;
    }
}

Troubleshooting

Common Issues

Issue	Cause	Solution
502 Bad Gateway	DNS resolution failed	Ensure `resolver` directive is set
404 Not Found	Incorrect `proxy_pass` URL	Verify trailing slash in `proxy_pass`
SSL Handshake Error	Missing SNI configuration	Add `proxy_ssl_server_name on;`
Content not loading	Wrong `Host` header	Ensure `Host` is set to `portal.pseo.one`

Debug Logging

Enable debug logging to troubleshoot issues:

error_log /var/log/nginx/error.log debug;
 
# Add debug header to responses
add_header X-Proxy-Source "Nginx-Config" always;

Check Nginx Logs

# View error logs
tail -f /var/log/nginx/error.log
 
# View access logs
tail -f /var/log/nginx/access.log
 
# Docker logs
docker logs -f my-nginx

Complete Working Example

Here is a complete, tested configuration for reference:

worker_processes  1;
 
events {
    worker_connections  1024;
}
 
http {
    include       mime.types;
    default_type  application/octet-stream;
 
    sendfile        on;
    keepalive_timeout  65;
 
    gzip  on;
    gzip_disable "msie6";
    gzip_types text/plain text/css application/json application/javascript text/xml application/xml application/xml+rss text/javascript;
 
    server {
        listen 80 default_server;
        server_name gopher-127-0-0-1.nip.io;
 
        location /news {
            resolver 8.8.8.8 1.1.1.1 valid=300s;
            resolver_timeout 5s;
 
            proxy_pass https://portal.pseo.one/;
 
            proxy_set_header Host portal.pseo.one;
            proxy_set_header x-req-domain http://gopher-127-0-0-1.nip.io/news;
 
            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;
 
            proxy_ssl_server_name on;
            proxy_ssl_name portal.pseo.one;
            proxy_ssl_session_reuse off;
 
            proxy_redirect off;
        }
    }
}

Additional Resources

For more detailed information on Nginx configuration: