ArchiveBox Behind Nginx: Configure the Reverse Proxy and Base URL

Set BASE_URL to the exact public HTTPS address people use, such as https://archive.example.com. Configure Nginx to forward requests to the ArchiveBox listener for your deployment. BASE_URL is the public canonical URL; BIND_ADDR is the local listening socket. They solve different problems.

For the current official Docker image, ArchiveBox listens on port 5797 inside the container. Your host-side port mapping can be different, so check your running image and Compose configuration before choosing the Nginx upstream. Older examples using ports such as 8000 or 8098 may not match a current deployment. ArchiveBox’s Docker image documentation and configuration reference describe the current settings.

1. Identify the public URL and ArchiveBox listener

Choose the canonical address first. It should include the scheme and hostname users will visit, with no internal container name or private port:

https://archive.example.com

Then identify the listener that Nginx can reach:

Setting	What it means	Typical consideration
BASE_URL	ArchiveBox’s canonical public URL, used for absolute links, redirects, notification email links, metadata, and some security-mode behavior.	Set it to the exact public HTTPS URL.
BIND_ADDR	The local address and port where ArchiveBox listens.	127.0.0.1:5797 suits a same-host proxy; 0.0.0.0:5797 allows Docker networking or LAN access.
Nginx upstream	The address and port Nginx connects to.	Use the host-mapped port for a host-installed Nginx, or the service name and container port when Nginx shares a Docker network.

Inside a container, binding to 127.0.0.1 makes the service reachable only within that container. A proxy in another container generally needs ArchiveBox to listen on a container-reachable interface such as 0.0.0.0. The correct upstream name and port depend on your network and port mapping.

2. Configure the canonical base URL

ArchiveBox accepts configuration through archivebox config --set, ArchiveBox.conf, or process environment variables. For a deployment where the command is available, set the canonical URL like this:

archivebox config --set BASE_URL=https://archive.example.com

Replace the example hostname with the public address users actually visit. If you configure the value through an environment variable or file instead, use the same exact URL. After changing deployment variables, check ArchiveBox’s effective configuration: persisted or scoped settings can take precedence over later environment changes.

When BASE_URL is explicitly set, ArchiveBox uses it instead of the incoming Host header when building URLs. That makes it the source of truth for the public scheme and hostname. Do not set it to the Nginx upstream, container name, loopback address, or an HTTP-only internal URL.

3. Point Nginx at the deployed listener

Configure the Nginx virtual host for archive.example.com to proxy to the listener reachable from the Nginx process. The current Docker image’s internal listener is 5797, but the proxy target depends on where Nginx runs:

• Nginx on the same host: use the host address and published host port from your Docker port mapping, or the loopback listener if ArchiveBox runs directly on that host.
• Nginx in the same Docker network: use the ArchiveBox service/container network name and its internal port, currently 5797 for the current official image.
• Nginx on another machine: use the reachable LAN address and port, and bind ArchiveBox to an interface accessible there.

The research sources for this guide do not provide a current directive-by-directive Nginx configuration. Avoid copying legacy proxy snippets without checking that their port, headers, and deployment assumptions match your version. ArchiveBox’s current Docker guide includes a first-run HTTPS setup wizard that provides proxy-specific DNS, upstream, and certificate settings, checks the resulting public HTTPS URLs, and saves BASE_URL and SERVER_SECURITY_MODE. Use that flow when it applies to your deployment: ArchiveBox Docker setup guide.

4. Handle HTTPS scheme and security mode

If BASE_URL is empty and ArchiveBox derives the scheme from a proxied request, its configuration reference specifies trusting X-Forwarded-Proto. With an explicit public BASE_URL, use the canonical HTTPS URL itself as the source of truth. This distinction commonly explains redirects that unexpectedly use HTTP.

ArchiveBox derives Django’s ALLOWED_HOSTS and CSRF_TRUSTED_ORIGINS from BASE_URL and SERVER_SECURITY_MODE. Do not reflexively paste old examples that hard-code these separately; first check the current configuration reference and your effective settings.

If you use safe-subdomains-fullreplay, explicitly pin BASE_URL. ArchiveBox documents it as required for redirects in that mode and displays a misconfiguration banner when it is missing.

5. Choose certificate coverage for your security mode

For a single public host, the HTTPS guide describes a certificate covering the BASE_URL hostname. If your setup needs ArchiveBox subdomains, the documented layout covers that host and *.BASE_URL, usually with DNS-01 validation. Follow the certificate requirements for your selected security mode; not every installation needs a wildcard certificate. The guide warns against on-demand TLS and individual certificates for snap-* hosts. See the official HTTPS setup guidance for the applicable layout.

6. Verify the public address end to end

1. Open the canonical HTTPS address in a browser and confirm the ArchiveBox page loads.
2. Follow a link generated by ArchiveBox. Confirm that it stays on the public hostname and uses HTTPS.
3. Check a redirect, such as a sign-in flow, for the same host and scheme.
4. If using the setup wizard, use its public URL checks and resolve any reported DNS, upstream, or certificate issue before relying on the instance.
5. Inspect the effective ArchiveBox configuration after any environment or file edits, especially if an old persisted value may override them.

Common problems and fixes

Symptom	Likely cause	What to check
ArchiveBox is unreachable through Nginx	The upstream points to the wrong port/address, or the listener is only bound to container loopback.	Check the deployed image version, Compose port mapping, Docker network, and BIND_ADDR. Current official Docker image guidance uses internal port 5797.
Generated links or redirects use the container name, private host, or wrong domain	BASE_URL is missing or does not match the public canonical address.	Set it to the full public HTTPS URL and verify the effective value.
Redirects use HTTP after HTTPS requests	ArchiveBox is deriving the request scheme while the proxy’s HTTPS scheme is not being trusted, or the canonical URL is set incorrectly.	Prefer an explicit HTTPS BASE_URL. If leaving it empty, follow the configuration reference’s forwarded-scheme guidance.
CSRF or allowed-host errors	The canonical URL or security mode does not agree with the requested public host.	Check BASE_URL and SERVER_SECURITY_MODE; ArchiveBox derives the related Django settings from them.
Subdomain replay redirects fail or a warning banner appears	BASE_URL is not explicitly configured in safe-subdomains-fullreplay mode.	Pin the public HTTPS URL and ensure certificate coverage matches the subdomain setup.
A copied setup guide uses a port that does not work	The guide targets an older image or a different host-port mapping.	Check the current container port and your deployment mapping rather than assuming a historic port is correct.
Changing an environment variable has no effect	A persisted or scoped setting has precedence.	Inspect ArchiveBox’s effective configuration and update the setting at the layer that currently supplies it.

Performance, reliability, and operating cost

The proxy/base URL setup does not itself change ArchiveBox capture performance. The practical reliability concerns here are reachability, correct public URL generation, and valid TLS coverage. Verify the public URL after changes, and make sure the upstream points to the listener exposed by the actual deployment. ArchiveBox documents host-mounted data storage, including an external USB drive as an option; separate storage is optional for this proxy setup and is not, by itself, a backup.

No measured latency, availability figure, or operating cost is established by the sources used for this guide. Infrastructure and storage costs depend on the host and deployment you choose.

Or skip the browser setup

If your goal is to capture a page rather than operate an archive, ScreenshotNeo is a website screenshot API and MCP server. One GET request returns an image or PDF; its options include full-page captures, selectors, custom CSS and JavaScript, and wait conditions. See the ScreenshotNeo API documentation.

curl -G "https://api.screenshotneo.com/v1/shot" -d access_key=YOUR_API_KEY --data-urlencode url=https://stripe.com -o shot.webp

import requests
r = requests.get("https://api.screenshotneo.com/v1/shot", params={"access_key": "YOUR_API_KEY", "url": "https://stripe.com"}, timeout=90)
open("shot.webp", "wb").write(r.content)

const q = new URLSearchParams({ access_key: 'YOUR_API_KEY', url: 'https://stripe.com' });
const res = await fetch(`https://api.screenshotneo.com/v1/shot?${q}`);

Cookie banners, popups, and chat widgets are removed before the shot. Bot checks, blank pages, and failed loads are never billed. An MCP server lets AI agents take screenshots. The free plan includes 1,000 screenshots a month with no card; paid plans start at $5 for 3,000.

Create a free ScreenshotNeo account to get 1,000 screenshots a month with no card.

FAQ

Should BASE_URL include a trailing slash?

Use the exact canonical URL format shown in ArchiveBox’s current configuration guidance. The essential requirements are the public hostname and HTTPS scheme; check the effective value after saving it.

Can I leave BASE_URL empty?

The configuration reference describes deriving the request scheme when it is empty, with X-Forwarded-Proto trusted. An explicit canonical URL is the straightforward choice when you want stable public links, and it is required in safe-subdomains-fullreplay mode.

Does every ArchiveBox deployment need a wildcard certificate?

No. Certificate coverage depends on whether your setup uses only the canonical host or also needs ArchiveBox subdomains.

Is port 5797 always the public Nginx port?

No. It is the internal listener port for the current official Docker image. A host mapping or another deployment can expose a different address and port.

Sources

• ArchiveBox Configuration reference
• ArchiveBox Docker image repository
• ArchiveBox Docker documentation