# How to Deploy GPT Academic Behind a Reverse Proxy Like Nginx

> Deploy GPT Academic behind Nginx. Learn how to configure FastAPI Gradio with WebSockets and increased upload limits for a secure and efficient setup. Follow our step by step guide.

- Repository: [binary-husky/gpt_academic](https://github.com/binary-husky/gpt_academic)
- Tags: how-to-guide
- Published: 2026-03-02

---

**Deploy GPT Academic behind Nginx by running the FastAPI/Gradio application on a local port, optionally setting a `CUSTOM_PATH` in [`config.py`](https://github.com/binary-husky/gpt_academic/blob/main/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`](https://github.com/binary-husky/gpt_academic/blob/main/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`](https://github.com/binary-husky/gpt_academic/blob/main/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`](https://github.com/binary-husky/gpt_academic/blob/main/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`](https://github.com/binary-husky/gpt_academic/blob/main/config.py)** before starting the server:

```python

# 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`](https://github.com/binary-husky/gpt_academic/blob/main/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:

```bash
python -m gpt_academic.main

```

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

```bash
curl http://127.0.0.1:7860

```

## Configuring Nginx as a Reverse Proxy

### Basic Nginx Installation

Install Nginx using your distribution’s package manager:

```bash

# 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`](https://github.com/binary-husky/gpt_academic/blob/main//etc/nginx/conf.d/gpt-academic.conf) (CentOS):

```nginx
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:

```bash
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`](https://github.com/binary-husky/gpt_academic/blob/main/config.py). Instead, terminate TLS at Nginx.

Install Certbot and obtain a certificate:

```bash
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`](https://github.com/binary-husky/gpt_academic/blob/main/shared_utils/fastapi_server.py) console output for uvicorn binding issues.

If you enabled `AUTHENTICATION` in [`config.py`](https://github.com/binary-husky/gpt_academic/blob/main/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`](https://github.com/binary-husky/gpt_academic/blob/main/shared_utils/fastapi_server.py) and [`main.py`](https://github.com/binary-husky/gpt_academic/blob/main/main.py), binding to a local port defined by `WEB_PORT`.
- **Set `CUSTOM_PATH`** in [`config.py`](https://github.com/binary-husky/gpt_academic/blob/main/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`](https://github.com/binary-husky/gpt_academic/blob/main/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`](https://github.com/binary-husky/gpt_academic/blob/main/config.py) to your desired sub‑directory (e.g., `CUSTOM_PATH = "/gpt"`). This value is mounted in [`shared_utils/fastapi_server.py`](https://github.com/binary-husky/gpt_academic/blob/main/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`](https://github.com/binary-husky/gpt_academic/blob/main/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`](https://github.com/binary-husky/gpt_academic/blob/main/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.