How to Deploy GPT Academic Behind a Reverse Proxy Like Nginx

Deploy GPT Academic behind Nginx by running the FastAPI/Gradio application on a local port, optionally setting a CUSTOM_PATH in config.py, and proxying traffic with WebSocket support and increased upload limits.

GPT Academic (binary-husky/gpt_academic) serves its Gradio interface through a FastAPI application managed by uvicorn. Because the stack uses standard HTTP and WebSocket protocols, you can place any reverse proxy in front of it. This guide explains the architecture, configuration keys in config.py, and the exact Nginx directives required for a production deployment.

Understanding the GPT Academic Architecture

When you launch the application via main.py, the entrypoint invokes shared_utils/fastapi_server.start_app. This function performs three critical steps:

1. Instantiates a Gradio Blocks object and applies authentication and queue settings.
2. Mounts the Gradio app on a custom path defined by the CUSTOM_PATH variable in config.py. By default this is /, but you can change it to a sub‑directory such as /gpt.
3. Starts uvicorn on the port specified by WEB_PORT (default 7860 or a random free port).

Because the service is a plain HTTP server, Nginx can terminate TLS, handle domain names, and forward traffic to the local uvicorn instance.

Prerequisites and Initial Configuration

Setting the Custom Path (Optional)

If you want the UI served under a sub‑directory rather than the domain root, edit config.py before starting the server:

# config.py

CUSTOM_PATH = "/gpt"   # UI will be available at https://your-domain.com/gpt/

This value is consumed in shared_utils/fastapi_server.py at line 16‑17 via fastapi_app.mount(CUSTOM_PATH, gradio_app).

Starting the Local Server

Launch GPT Academic so it binds to the local interface:

python -m gpt_academic.main

By default this starts uvicorn on 0.0.0.0:7860. Verify it responds locally:

curl http://127.0.0.1:7860

Configuring Nginx as a Reverse Proxy

Basic Nginx Installation

Install Nginx using your distribution’s package manager:

# Ubuntu / Debian

sudo apt update && sudo apt install nginx

# CentOS / RHEL

sudo yum install nginx

# Enable and start the service

sudo systemctl enable --now nginx

Complete Nginx Configuration

Create a site configuration file at /etc/nginx/sites-available/gpt-academic (Debian/Ubuntu) or /etc/nginx/conf.d/gpt-academic.conf (CentOS):

server {
    listen 80;
    server_name your-domain.com;  # Replace with your actual domain

    # Optional: Redirect HTTP to HTTPS after certbot setup

    # listen 443 ssl http2;

    # ssl_certificate /etc/letsencrypt/live/your-domain.com/fullchain.pem;

    # ssl_certificate_key /etc/letsencrypt/live/your-domain.com/privkey.pem;

    location / {
        # If you set CUSTOM_PATH = "/gpt" in config.py, use:

        # location /gpt/ { proxy_pass http://127.0.0.1:7860/; }

        proxy_pass http://127.0.0.1:7860;

        # Preserve original host and client IP

        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;

        # WebSocket support (required for Gradio's real-time UI)

        proxy_http_version 1.1;
        proxy_set_header Upgrade $http_upgrade;
        proxy_set_header Connection "upgrade";

        # Allow large file uploads for document processing plugins

        client_max_body_size 100M;

        # Extended timeouts for LLM inference

        proxy_connect_timeout 300s;
        proxy_send_timeout 300s;
        proxy_read_timeout 300s;

        # Disable buffering for streaming responses

        proxy_buffering off;
    }

    access_log /var/log/nginx/gpt-academic.access.log;
    error_log /var/log/nginx/gpt-academic.error.log;
}

Enable the configuration and verify syntax:

sudo ln -s /etc/nginx/sites-available/gpt-academic /etc/nginx/sites-enabled/
sudo nginx -t
sudo systemctl reload nginx

Enabling HTTPS with Let's Encrypt

Because the FastAPI server runs behind the proxy, you do not need to configure SSL_KEYFILE or SSL_CERTFILE in config.py. Instead, terminate TLS at Nginx.

Install Certbot and obtain a certificate:

sudo apt install certbot python3-certbot-nginx
sudo certbot --nginx -d your-domain.com

Certbot automatically updates the Nginx configuration with the listen 443 ssl block and sets up auto-renewal. The uvicorn server continues to run plain HTTP on the local port, while Nginx handles encryption.

Verification and Troubleshooting

After deployment, verify the reverse proxy configuration:

1. Load the UI: Open https://your-domain.com (or /gpt if you set a custom path). The Gradio interface should appear without mixed-content errors.
2. Test WebSocket functionality: Start a chat; messages should appear in real time. If the UI hangs, check that proxy_set_header Upgrade and Connection "upgrade" are present.
3. Upload a large file: Use a document processing plugin to upload a PDF or ZIP > 10 MB. If you receive a 413 Payload Too Large error, increase client_max_body_size.
4. Review logs: Check /var/log/nginx/gpt-academic.error.log for routing errors and shared_utils/fastapi_server.py console output for uvicorn binding issues.

If you enabled AUTHENTICATION in config.py, the FastAPI server already protects /file/* routes. You can add an additional Basic Auth layer in Nginx using auth_basic if you wish to restrict access to the proxy endpoint itself.

Summary

• GPT Academic runs a FastAPI/Gradio stack via shared_utils/fastapi_server.py and main.py, binding to a local port defined by WEB_PORT.
• Set CUSTOM_PATH in config.py if you need to serve the UI under a sub‑directory (e.g., /gpt).
• Configure Nginx to proxy HTTP and WebSocket traffic, forwarding headers (X-Forwarded-For, Host), enabling Upgrade headers, and increasing client_max_body_size for file uploads.
• Terminate TLS at Nginx using Let’s Encrypt; leave SSL_KEYFILE and SSL_CERTFILE empty in config.py because the uvicorn server runs behind the proxy.
• Verify WebSocket functionality and large file uploads to ensure the reverse proxy configuration is complete.

Frequently Asked Questions

How do I change the URL path for GPT Academic when using a reverse proxy?

Edit the CUSTOM_PATH variable in config.py to your desired sub‑directory (e.g., CUSTOM_PATH = "/gpt"). This value is mounted in shared_utils/fastapi_server.py via fastapi_app.mount(CUSTOM_PATH, gradio_app). Ensure your Nginx location block matches this path (e.g., location /gpt/ { proxy_pass http://127.0.0.1:7860/; }).

Why does the Gradio interface hang or fail to update when proxied?

Gradio requires WebSocket support for real‑time chat updates. If the UI becomes unresponsive, verify that your Nginx configuration includes proxy_http_version 1.1;, proxy_set_header Upgrade $http_upgrade;, and proxy_set_header Connection "upgrade";. These headers allow the connection to upgrade from HTTP to WebSocket.

Should I configure SSL in config.py or in Nginx when using a reverse proxy?

Configure SSL in Nginx, not in config.py. Terminate TLS at the reverse proxy by installing a certificate (e.g., via Let’s Encrypt) in Nginx and leaving SSL_KEYFILE and SSL_CERTFILE empty in config.py. The internal uvicorn server should run plain HTTP on 127.0.0.1 so Nginx can proxy to it securely.

How do I fix "413 Payload Too Large" errors when uploading files?

Increase the client_max_body_size directive in your Nginx server block. GPT Academic plugins such as PDF Translate or Document Conversation often upload large archives, so set a generous limit (e.g., client_max_body_size 100M; or higher depending on your use case) and reload Nginx.

{
  "mcpServers": {
    "instagit": {
      "command": "npx",
      "args": ["-y", "instagit@latest"]
    }
  }
}