---

---

Overview

NextTrace Web is a spin-off of the NextTrace project. It provides a simple web frontend and API server so you can run traceroutes and visualize results — including hop, IP, ASN, geolocation, domain, packet loss, and latency stats — entirely from your browser.

Reverse proxy note: This project uses WebSocket as its communication protocol. If you configure a reverse proxy, please refer to the Nginx config included in this repository. The provided Docker image already has Nginx reverse proxy built in.

Inspired by PING.PE — thanks for years of keeping that service alive and giving the community such a great reference.

---

How To Use

Docker (Recommended)

docker pull tsosc/nexttraceweb
docker run --network host -d --privileged --name ntwa tsosc/nexttraceweb 127.0.0.1:30080
# Visit http://127.0.0.1:30080

Expose the service to the Internet through your own reverse proxy or gateway. This project does not ship an in-app login flow.

Custom Address & Port

Pass an address/port argument to docker run to override the default:

# Bind to localhost only
docker run --network host -d --privileged --name ntwa tsosc/nexttraceweb 127.0.0.1:30080

# Listen on all IPs, port 80
docker run --network host -d --privileged --name ntwa tsosc/nexttraceweb 80

# Listen on IPv6 loopback
docker run --network host -d --privileged --name ntwa tsosc/nexttraceweb [::1]:30080

Interface Language

The UI ships English and Simplified Chinese. The selector in the page header defaults to Auto, which follows the browser's Accept-Language preference; pick English or 中文 to pin one. The choice is stored in localStorage under uiLanguage.

The separate Geo Data Language option inside the settings drawer is unrelated — it is passed straight to nexttrace and controls the language of geolocation data, not the interface.

Sub-path Deployment

All assets, the /api/devices endpoint, and the Socket.IO path are resolved relative to the page's own directory, so the app can be mounted under a sub-path. The outer proxy must strip the prefix (note the trailing slash on both location and proxy_pass) and redirect the prefix without a trailing slash:

# In the http block. $connection_upgrade is not a built-in variable:
map $http_upgrade $connection_upgrade {
    default upgrade;
    ''      close;
}

# In the server block. https://example.com/tools/nexttrace/ maps to the container root:
location = /tools/nexttrace {
    return 301 /tools/nexttrace/$is_args$args;
}

location /tools/nexttrace/ {
    proxy_http_version 1.1;
    proxy_set_header Host $http_host;
    proxy_set_header Upgrade $http_upgrade;
    proxy_set_header Connection $connection_upgrade;
    proxy_pass http://127.0.0.1:30080/;
}

Both trailing slashes matter. Drop the one on proxy_pass and the backend receives /tools/nexttrace/..., for which it has no route. The 301 covers visitors who leave the trailing slash out of the address bar: the browser resolves relative references against the parent directory, so the assets would be fetched from /tools/assets/... and the page would render unstyled.

Runtime Notes

• Health endpoint: GET /healthz
• The container now exits when gunicorn or nginx dies, so supervisors can restart it instead of leaving a half-dead process tree behind.
• nexttrace_error is now a structured payload with code and message, plus retry_after_seconds on rate-limit and capacity rejections.

Security Defaults

• Configure NTWA_SECRET_KEY in production. If omitted, the app generates a temporary random key and logs a warning.
• Recommended: set NTWA_TRUSTED_HOSTS=trace.example.com behind a reverse proxy.
• Set NTWA_SESSION_COOKIE_SECURE=true only when the outer proxy serves HTTPS.
• Abuse controls:
  • NTWA_MIN_START_INTERVAL_SECONDS
  • NTWA_MAX_ACTIVE_TRACES
  • NTWA_TRACE_IDLE_TIMEOUT_SECONDS
  • NTWA_TRACE_MAX_DURATION_SECONDS

External Auth Example

Minimal Nginx example with Basic Auth in front of the container:

server {
    listen 443 ssl http2;
    server_name trace.example.com;

    auth_basic "restricted";
    auth_basic_user_file /etc/nginx/.htpasswd;

    location / {
        proxy_http_version 1.1;
        proxy_set_header Host $host;
        proxy_set_header Upgrade $http_upgrade;
        proxy_set_header Connection $connection_upgrade;
        proxy_pass http://127.0.0.1:30080;
    }
}