Skip to content

Serve TestGen Through a Reverse Proxy

Use a reverse proxy to serve the TestGen UI, the REST API, and the MCP server on one HTTPS address on the standard port 443, such as https://testgen.example.com, instead of on ports 8501 and 8530. One address on port 443 is simpler to share, passes through networks that allow only standard HTTPS, and is required by hosted clients that connect only on that port, such as custom connectors in Claude.ai.

To keep serving the UI and the API on their own ports, over HTTPS, see Configure HTTPS instead. On Kubernetes, configure the chart's ingress as in Install on Kubernetes instead of setting up NGINX.

Set up an NGINX reverse proxy

The steps use NGINX in a container next to TestGen. The proxy holds the certificate, and TestGen serves plain HTTP on the Docker network.

These steps require the following.

  • TestGen instance installed using dk-installer.exe, as outlined in Install on Windows, or dk-installer, as outlined in Install on Mac/Linux or Install Enterprise.

  • An SSL certificate file and its private key file, in PEM format, for the domain used to access TestGen.

  • Navigate to the directory that contains the docker-compose.yml file for TestGen.

    • If the instance was installed using dk-installer.exe, the file can be located under "AppData\Local\DataKitchenApps".
    • If the instance was installed using dk-installer, the file can be located in the folder from which the Python installer was executed.

  • Copy the certificate and key into the directory as domain.crt and domain.key.

  • Create an nginx.conf file in the directory with the following contents. Replace <host> with the host name on your certificate.

    events {}

http {
    server_tokens off;

    server {
        listen 443 ssl;
        server_name <host>;

        ssl_certificate     /etc/ssl/domain.crt;
        ssl_certificate_key /etc/ssl/domain.key;
        ssl_protocols TLSv1.2 TLSv1.3;

        # API and MCP server
        location ~ ^/(mcp(/|$)|api/|oauth/|\.well-known/) {
            proxy_pass http://engine:8530;
            proxy_set_header Host $host;
            proxy_set_header X-Forwarded-For $proxy_add_x_forwarded_for;
            proxy_set_header X-Forwarded-Proto $scheme;
            proxy_http_version 1.1;
            proxy_buffering off;
            proxy_read_timeout 3600s;
            client_max_body_size 10m;
        }

        # UI
        location / {
            proxy_pass http://engine:8501;
            proxy_set_header Host $host;
            proxy_set_header X-Forwarded-For $proxy_add_x_forwarded_for;
            proxy_http_version 1.1;
            proxy_set_header Upgrade $http_upgrade;
            proxy_set_header Connection "upgrade";
            proxy_read_timeout 86400;
        }
    }

    server {
        listen 80;
        return 301 https://$host$request_uri;
    }
}

    Keep proxy_buffering off and the long proxy_read_timeout values: MCP streams its responses, and the UI holds a WebSocket connection open. If you set TG_API_MAX_REQUEST_BODY_BYTES, set client_max_body_size to match.

  • In docker-compose.yml, add an nginx service, with the same networks as the engine service.

    services:
  nginx:
    image: nginx:1.30
    container_name: nginx
    restart: unless-stopped
    ports:
      - 443:443
      - 80:80
    volumes:
      - ./nginx.conf:/etc/nginx/nginx.conf:ro
      - ./domain.crt:/etc/ssl/domain.crt:ro
      - ./domain.key:/etc/ssl/domain.key:ro
    networks:
      - datakitchen
    depends_on:
      - engine

  • In the engine service, remove the ports section so that all traffic goes through the proxy. If the service mounts a certificate as in Configure HTTPS, remove those bind mounts as well.

  • Set the following variables under the x-common-variables section. Use the host name on your certificate, without a port. If SSL_CERT_FILE and SSL_KEY_FILE are set, remove them.

    x-common-variables: &common-variables
 TG_UI_BASE_URL: https://<host>
 TG_BASE_URL: https://<host>

  • Restart the application.

    docker compose up -d --wait

  • Open port 443 in the firewall or security group of the TestGen server. Ports 8501 and 8530 do not need to be open.

Note

AI clients and integrations configured with a URL on port 8530 stop connecting. Update them to https://<host>/mcp for MCP, or https://<host>/api/v1 for the REST API.

Use your own reverse proxy

To serve TestGen through a reverse proxy or load balancer that you already run, configure it to send requests whose path starts with one of the following prefixes to the REST API and MCP port (8530), and all other requests to the UI port (8501).

Path prefix Serves
/api/ REST API and its reference documentation
/mcp MCP server
/oauth/ OAuth sign-in and token endpoints
/.well-known/ OAuth discovery metadata

The proxy must also:

  • Pass the Host header through unchanged. If the proxy rewrites it, add the host name it sends to the TG_MCP_EXTRA_ALLOWED_HOSTS environment variable.
  • Turn off response buffering for /mcp.
  • Accept request bodies of up to 10 MB on the REST API and MCP paths, or up to TG_API_MAX_REQUEST_BODY_BYTES if you set it.
  • Allow WebSocket connections to the UI, and keep idle connections open for at least 90 seconds.
  • If the proxy or a CDN caches responses, include the query string in the cache key.

If the proxy or load balancer checks health, use /_stcore/health for the UI and /api/v1/health for the REST API and MCP server.

Then set TG_UI_BASE_URL and TG_BASE_URL to https://<host>. See Set Environment Variables.

Serve TestGen under a path

To share a host with other applications, serve TestGen under a path, such as https://<host>/testgen. These steps apply to any reverse proxy or load balancer, however TestGen is installed.

  1. Set TG_UI_BASE_URL and TG_BASE_URL to https://<host>/testgen. TestGen serves the UI, the REST API, and the MCP server under that path. See Set Environment Variables.
  2. Configure the proxy or load balancer to forward the following requests without removing the path. It must also meet the requirements in Use your own reverse proxy.
    • Send /testgen/api/, /testgen/mcp, /testgen/oauth/, /.well-known/oauth-authorization-server/testgen, and /.well-known/oauth-protected-resource/testgen/mcp to the API and MCP port (8530). The two /.well-known/ paths are at the root of the host, not under /testgen.
    • Send all other requests under /testgen to the UI port (8501).
    • Redirect /testgen to /testgen/, keeping the query string.
  3. If the proxy or load balancer checks health, use /testgen/_stcore/health for the UI and /testgen/api/v1/health for the API and MCP server.
  4. Enterprise If you use single sign-on, set the redirect URI in your identity provider and redirect_uri in sso_auth.toml to https://<host>/testgen/, including the path and its trailing slash. See Configure Single Sign-On.
  5. Configure AI clients and integrations with https://<host>/testgen/mcp for MCP, or https://<host>/testgen/api/v1 for the REST API.

To use different paths for the UI and the API, such as https://<host>/testgen for TG_UI_BASE_URL and https://<host>/testgen-api for TG_BASE_URL, send all requests under the API path to port 8530, and use the API path in the two /.well-known/ paths, such as /.well-known/oauth-protected-resource/testgen-api/mcp.