How to Configure SSL/HTTPS for the GPT-Academic Web Interface

To enable HTTPS in GPT-Academic, set the SSL_KEYFILE and SSL_CERTFILE variables in config.py to point to your private key and certificate files, then restart the application to start the uvicorn server with TLS enabled.

The GPT-Academic project provides a web interface built on Gradio Blocks, wrapped in a FastAPI application and served by uvicorn. According to the source code in binary-husky/gpt_academic, the server can be configured to terminate TLS directly by passing certificate paths through the configuration layer to the uvicorn Config object. This guide explains how to configure SSL/HTTPS for the web interface using either direct TLS termination or a reverse proxy setup.

How SSL/TLS Works in GPT-Academic

The application stack consists of three layers: Gradio provides the UI components, FastAPI handles the HTTP routing, and uvicorn serves as the ASGI server. In shared_utils/fastapi_server.py, the start_app function initializes a uvicorn.Server using a uvicorn.Config instance. When the configuration variables SSL_KEYFILE and SSL_CERTFILE are populated, their values are passed directly to the ssl_keyfile and ssl_certfile parameters of the uvicorn Config constructor, enabling native HTTPS support without additional proxies.

The configuration flow follows this path:

1. config.py stores the file paths (lines 211–214)
2. main.py retrieves them via get_conf (lines 53–55)
3. fastapi_server.py applies them to the uvicorn configuration

Step-by-Step Configuration

Generate or Obtain SSL Certificates

You can use certificates signed by a trusted Certificate Authority (CA) such as Let’s Encrypt, or generate a self-signed pair for local testing. To create a self-signed certificate with OpenSSL:

mkdir -p cert
openssl req -x509 -nodes -days 365 \
    -newkey rsa:2048 \
    -keyout cert/gpt_academic.key \
    -out cert/gpt_academic.crt \
    -subj "/C=CN/ST=State/L=City/O=Organization/OU=Dept/CN=your.domain.com"

This command generates gpt_academic.key (the private key) and gpt_academic.crt (the public certificate) in the cert/ directory. The process must have read permissions for these files.

Configure the Application

Open config.py in the repository root and locate the SSL configuration section (near line 211). Set the paths to your certificate files:

# config.py

SSL_KEYFILE = "cert/gpt_academic.key"   # Path to the private key

SSL_CERTFILE = "cert/gpt_academic.crt"  # Path to the certificate

Use absolute paths if the application is started from a different working directory. If you are using a reverse proxy instead, leave these values empty or set to None.

Start the Server

Run the main entry point. The application reads the SSL configuration via get_conf in main.py and passes the parameters to the uvicorn server:

python main.py

When TLS is active, the console output will indicate HTTPS instead of HTTP:

INFO:     Uvicorn running on https://127.0.0.1:7860 (Press CTRL+C to quit)

Access the interface at https://localhost:7860/. If you configured a custom path via CUSTOM_PATH (e.g., CUSTOM_PATH = "/gpt_academic"), the URL becomes https://localhost:7860/gpt_academic/.

Alternative: Reverse Proxy Setup

For production deployments, you may prefer to terminate TLS at a reverse proxy such as Nginx, Apache, or a cloud load balancer. In this architecture:

1. Leave SSL_KEYFILE and SSL_CERTFILE empty in config.py so the application runs on plain HTTP.
2. Configure the proxy to forward traffic to the internal Gradio port (default 7860).

Example Nginx configuration:

server {
    listen 443 ssl;
    server_name your.domain.com;

    ssl_certificate     /etc/ssl/certs/gpt_academic.crt;
    ssl_certificate_key /etc/ssl/private/gpt_academic.key;

    location / {
        proxy_pass http://127.0.0.1:7860/;
        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;
    }
}

This approach centralizes certificate management and allows you to run multiple services on standard ports while the GPT-Academic backend remains isolated on a local port.

Summary

• Direct TLS: Set SSL_KEYFILE and SSL_CERTFILE in config.py to enable native HTTPS via uvicorn.
• File locations: Store certificates in a readable path (e.g., cert/) and reference them relative to the working directory or use absolute paths.
• Reverse proxy: For production, leave SSL variables empty and terminate TLS at Nginx or a load balancer, forwarding plain HTTP to port 7860.
• Access URL: Use https:// followed by the host and port (default 7860), appending CUSTOM_PATH if configured.

Frequently Asked Questions

Can I use self-signed certificates for testing?

Yes. Self-signed certificates are fully supported for development environments. Generate them with OpenSSL as shown in the step-by-step guide. Browsers will display a security warning because the certificate is not signed by a trusted CA, but you can proceed after acknowledging the risk. For production, use certificates from a trusted authority like Let’s Encrypt.

What file formats are supported for the SSL certificates?

The implementation relies on uvicorn’s SSL configuration, which expects PEM-encoded files. The private key should be in a standard PEM format (often .key or .pem), and the certificate file should contain the full certificate chain in PEM format (often .crt or .pem). Ensure the files are unencrypted (no password protection) so the server can read them without interactive input.

Why does my browser show a warning when using HTTPS?

If you are using a self-signed certificate or a certificate signed by an internal CA not trusted by your operating system, browsers will flag the connection as insecure. To resolve this for production, obtain a certificate from a publicly trusted CA. For internal networks, you can import your root CA certificate into the browser’s trust store or use the reverse proxy method to handle certificates at the edge.

Can I run HTTPS on a custom port?

Yes. The HTTPS port is determined by the WEB_PORT variable in config.py. Set it to your desired port (e.g., WEB_PORT = 8443) and ensure the port is open in your firewall. When both SSL_KEYFILE and SSL_CERTFILE are configured, uvicorn will bind to that port using HTTPS automatically.

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