Nginx Configuration

This guide explains how to configure Nginx as a reverse proxy for your Gigantics instance. Nginx provides SSL termination, load balancing, and improved performance for your Gigantics deployment.

Overview

Gigantics runs on port 5000 by default and can be accessed directly or through Nginx as a reverse proxy. The setup includes:

• SSL/TLS termination
• HTTP to HTTPS redirection
• WebSocket support for real-time features
• Large file upload support
• Proper header forwarding

Installation

Nginx is not provided with the software, you can download it yourself from:

Official Website: https://nginx.org/

Installation Commands

Ubuntu/Debian:

sudo apt update
sudo apt install nginx

CentOS/RHEL/Rocky Linux:

sudo yum install nginx
# or for newer versions
sudo dnf install nginx

macOS (with Homebrew):

brew install nginx

Windows: Download the Windows version from the official website and follow the installation wizard.

Start and Enable Nginx

# Start Nginx
sudo systemctl start nginx

# Enable Nginx to start on boot
sudo systemctl enable nginx

# Check status
sudo systemctl status nginx

Direct Connection vs Nginx Proxy

Direct Connection to Port 5000

You can access Gigantics directly by connecting to http://yourserver:5000 without any reverse proxy (ie Nginx). This is the simplest setup and works for:

• Development environments
• Internal networks where security is handled at the network level
• Quick testing and evaluation

What's behind port 5000: Gigantics runs on a Node.js Express server that provides:

• HTTP/HTTPS web server capabilities
• REST API endpoints
• GraphQL API with WebSocket support
• Static file serving for the web interface
• Built-in session management and authentication
• File upload handling
• Real-time communication via WebSockets

Using Nginx as Reverse Proxy

While direct connection works, using Nginx as a reverse proxy offers significant advantages:

When to Use Each Approach

Use Direct Connection when:

• Setting up for development or testing
• Running in a secure internal network
• You need the simplest possible setup
• SSL is handled by a load balancer or cloud service

Use Nginx Proxy when:

• Deploying to production
• You need SSL/TLS termination
• Performance and scalability are important
• You want advanced security features
• You need to serve multiple applications
• You want better monitoring and logging

Production Configuration

Here's the recommended Nginx configuration for Gigantics:

server {
    server_name yourserver.com;
    listen 80;
    listen 443 ssl;

    # SSL Configuration
    ssl_certificate /etc/nginx/certs/your_certificate.crt;
    ssl_certificate_key /etc/nginx/certs/your_private_key.key;

    # Security headers
    add_header X-Frame-Options DENY;
    add_header X-Content-Type-Options nosniff;
    add_header X-XSS-Protection "1; mode=block";
    add_header Strict-Transport-Security "max-age=31536000; includeSubDomains" always;

    # Client settings for large file uploads
    client_max_body_size 500m;
    client_body_buffer_size 4m;
    large_client_header_buffers 4 32k;

    # Main location block
    location / {
        proxy_pass http://localhost:5000;
        proxy_redirect off;

        # Essential headers
        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-Host $host;
        proxy_http_version 1.1;
        proxy_set_header Upgrade $http_upgrade;
        proxy_set_header Connection "upgrade";

        # Timeout settings
        proxy_connect_timeout 90;
        proxy_send_timeout 90;
        proxy_read_timeout 90;

        # Buffer settings
        proxy_buffer_size 4k;
        proxy_buffers 4 32k;
        proxy_busy_buffers_size 64k;
        proxy_temp_file_write_size 64k;
    }
}

Configuration Parameters Explained

Server Block Settings

SSL Configuration

Client Upload Settings

Proxy Headers

Timeout Settings

Buffer Settings

HTTP to HTTPS Redirection

To automatically redirect HTTP traffic to HTTPS:

server {
    listen 80;
    server_name yourserver.com;
    return 301 https://$server_name$request_uri;
}

Security Headers

Add these security headers for enhanced protection:

add_header X-Frame-Options DENY;
add_header X-Content-Type-Options nosniff;
add_header X-XSS-Protection "1; mode=block";
add_header Strict-Transport-Security "max-age=31536000; includeSubDomains" always;

Load Balancing (Optional)

For high-availability setups, you can configure load balancing:

upstream gigantics_backend {
    server 192.168.0.7:5000;
    server 192.168.0.8:5000;
    server 192.168.0.9:5000;
}

server {
    # ... other configuration ...

    location / {
        proxy_pass http://gigantics_backend;
        # ... other proxy settings ...
    }
}

Testing Your Configuration

Testing Direct Connection

Before setting up Nginx, test that Gigantics is accessible directly:

1. Check if Gigantics is running:

   curl http://localhost:5000
   # or
   curl http://yourserver:5000

2. Test WebSocket connection:

   # Test GraphQL endpoint
   curl -X POST http://localhost:5000/graphql \
     -H "Content-Type: application/json" \
     -d '{"query":"{ __schema { types { name } } }"}'

Testing Nginx Configuration

1. Test Nginx configuration:

   sudo nginx -t

2. Reload Nginx:

   sudo systemctl reload nginx

3. Check Nginx status:

   sudo systemctl status nginx

4. Test through Nginx:

   curl https://yourserver.com

Troubleshooting

Common Issues

Log Files

Check these log files for debugging:

• Nginx error log: /var/log/nginx/error.log
• Nginx access log: /var/log/nginx/access.log
• Gigantics logs: Check your configured logs location

Integration with Gigantics Setup

When setting up Gigantics with Nginx, ensure:

1. Enable Nginx in setup: Check the "Enable Nginx" option in the advanced setup
2. Configure SSL: Provide your SSL certificate and key paths
3. Set redirect port: Configure HTTP to HTTPS redirection if needed
4. Update server configuration: Ensure Gigantics listens on the correct interface

The setup process will generate the appropriate Nginx configuration based on your settings.

Optional: Dedicated GraphQL Location Block

While the main location block handles all requests including GraphQL, you can optionally add a dedicated /graphql location block for enhanced WebSocket support and specific optimizations.

When to Use a Dedicated GraphQL Block

Use this optional configuration when:

• You need enhanced WebSocket performance for GraphQL subscriptions
• You want different timeout settings for GraphQL operations
• You need specific caching rules for GraphQL queries
• You want to separate GraphQL traffic from regular web traffic
• You're experiencing WebSocket connection issues with the main location block

Optional GraphQL Configuration

You may add this location block after your main location block:

server {
    # ... all the other config goes here ...

    # Optional: Dedicated GraphQL location block
    location /graphql {
        proxy_pass http://192.168.0.7:5000;
        proxy_http_version 1.1;
        proxy_set_header Upgrade $http_upgrade;
        proxy_set_header Connection "upgrade";
        proxy_set_header Host $host;
        proxy_set_header X-Real-IP $remote_addr;
        proxy_set_header X-Forwarded-For $proxy_add_x_forwarded_for;

        # GraphQL-specific optimizations
        proxy_connect_timeout 60s;
        proxy_send_timeout 60s;
        proxy_read_timeout 300s;  # Longer for subscriptions

        # WebSocket-specific settings
        proxy_cache_bypass $http_upgrade;
        proxy_no_cache $http_upgrade;
    }
}

Configuration Options for GraphQL Block

Why This is Optional

The main location block already handles GraphQL because:

• It includes proxy_http_version 1.1
• It has Upgrade and Connection headers for WebSocket support
• Gigantics handles GraphQL routing internally

Use the dedicated block only if you need:

• Different timeout settings for GraphQL vs regular requests
• Enhanced WebSocket performance for real-time features
• Specific caching behavior for GraphQL queries
• Troubleshooting WebSocket connection issues

Testing GraphQL Configuration

Test both regular and GraphQL endpoints:

# Test regular GraphQL (through main location)
curl -X POST https://yourserver.com/graphql \
  -H "Content-Type: application/json" \
  -d '{"query":"{ __schema { types { name } } }"}'

# Test WebSocket connection (if using dedicated block)
# This requires a WebSocket client or browser developer tools