How to Install ArchiveBox on Ubuntu with Docker Compose

To install ArchiveBox on Ubuntu, install Docker Engine and Docker Compose v2, download ArchiveBox’s official Compose file, pull the image, and start the service. The current quickstart uses container port 5797 and stores the collection in a persistent data directory. After it starts, open /admin/ on the machine’s hostname or IP to complete first-run setup.

1. Check the Ubuntu host

The ArchiveBox Docker deployment guide lists Ubuntu on amd64 and arm64 as supported. Its Compose setup requires Docker Engine or Docker Desktop with Docker Compose v2. Confirm Docker and Compose are installed and available to your account before continuing:

docker --version
docker compose version

The second command should report Compose v2. If either command is missing, install Docker using its current official Ubuntu instructions, then return here. Installation commands for Docker itself can change over time, so use the documentation for your Ubuntu release rather than copying an unverified package setup.

2. Download the official Compose file and start ArchiveBox

Run the current upstream quickstart commands. They create the project directory and persistent collection directory, fetch the Compose file, pull its image, and start the service:

mkdir -p ~/archivebox/data && cd ~/archivebox
curl -fsSL https://raw.githubusercontent.com/ArchiveBox/docker-archivebox/main/docker-compose.yml -o docker-compose.yml
docker compose pull
docker compose up -d --wait

The project directory is ~/archivebox; the host-side collection data is in ~/archivebox/data. Keep this directory in a stable location. The Compose file comes from a mutable branch, so the image and configuration it selects may change over time.

Inspect the Compose configuration

Before starting, or when reviewing a deployment later, inspect the downloaded file and the resolved configuration:

cd ~/archivebox
a less docker-compose.yml
docker compose config

The deployment guide describes a container listener on port 5797. The host port can be changed with ARCHIVEBOX_PORT; the container continues to listen on 5797. Check the actual Compose file if you need to confirm the published host port or environment settings.

3. Complete first-run administration

Open http://HOSTNAME-OR-IP:PORT/admin/, replacing the hostname or IP with the address used to reach this Ubuntu machine and the port published by your Compose configuration. Complete the setup wizard. It configures the canonical URL and security mode.

The documented configuration options include:

ARCHIVEBOX_PORT: changes the host port published for the web service. The container-side listener remains port 5797.
BASE_URL: overrides the canonical URL used by ArchiveBox.
SERVER_SECURITY_MODE: overrides the security mode configured through the wizard.
ADMIN_USERNAME and ADMIN_PASSWORD: optional environment variables for creating an administrator without the interactive wizard.

Use the wizard for a basic first run. If you configure environment variables instead, add them in the Compose configuration or its supported environment file, then recreate the service so the container receives the updated values. Do not expose administrator credentials in shell history or commit them to a repository.

4. Verify the service and archive a test URL

Check the installed version, add one URL, inspect the collection status, and follow the service logs:

cd ~/archivebox
docker compose exec archivebox archivebox version
docker compose exec archivebox archivebox add --depth=1 'https://example.com'
docker compose exec archivebox archivebox status
docker compose logs -f archivebox

Stop following logs with Ctrl+C; this does not stop the container. The image also provides a /health/ health check. For a one-off command when the service is not already running, the deployment documentation distinguishes docker compose run --rm archivebox ... from docker compose exec archivebox ..., which runs a command inside the existing service container.

5. Persistence, updates, and reproducibility

Protect the collection data

The host-side data directory is the persistent collection location mounted by Compose. Back it up according to how much archive data you can afford to lose. A practical backup should account for the collection’s size and should be stored separately from the Ubuntu host. The installation guide identifies the persistent directory but does not prescribe a backup schedule or backup product.

Understand what the quickstart pins

The quickstart downloads the Compose file from the repository’s moving main branch, and the current guide describes a development image deployment. The sources do not specify a fixed image version for this workflow. For a reproducible deployment, inspect the Compose file, select a reviewed image version or commit according to your maintenance policy, and record that choice. Do not assume a mutable quickstart will reproduce the same image later.

Choose a port that fits the host

If the default host port conflicts with another service, configure ARCHIVEBOX_PORT and use that port in the browser URL. Changing the host port does not change the container listener, which remains 5797 according to the current deployment guide. Confirm the host port mapping in docker compose config.

6. Troubleshooting

Symptom	Likely cause	What to do
`docker compose` is not recognized	Compose v2 is not installed or the Docker CLI plugin is unavailable.	Install or repair Docker Compose v2 for the Ubuntu host, then check `docker compose version`.
Docker commands fail with a permission error	The current user cannot access the Docker daemon.	Use the host’s configured Docker access method, or run the command with the required administrator privileges. Recheck access with `docker info`.
The Compose download fails or produces an empty file	The host cannot reach GitHub, or the request failed.	Retry the documented `curl -fsSL` download and verify that `docker-compose.yml` exists and contains the expected configuration before running Compose.
`docker compose up -d --wait` does not complete successfully	The image may still be downloading, the service may fail to start, or a required port may be unavailable.	Inspect `docker compose ps` and `docker compose logs archivebox`. Resolve the reported startup issue; if the host port is occupied, choose another `ARCHIVEBOX_PORT`.
The browser cannot open the admin page	The URL may use the wrong host port, the service may not be healthy, or the host may not be reachable from the client.	Check `docker compose ps`, review the port mapping with `docker compose config`, and use the host’s reachable hostname or IP plus the configured port and `/admin/`.
The setup wizard uses an unexpected canonical URL or security mode	`BASE_URL` or `SERVER_SECURITY_MODE` may override the wizard’s settings.	Review the effective Compose configuration and set the desired environment values, or remove the overrides and restart the service.
The test archive command cannot reach the target page	The Ubuntu host or container may lack network access, or the target may not be reachable from that environment.	Check the service logs and connectivity from the host. Retry with a URL the host can access and inspect the resulting status.

7. Performance, reliability, and cost considerations

This deployment procedure does not establish a setup-time, capture-speed, or reliability benchmark. Archive work depends on the pages being collected and the host’s available resources; size the Ubuntu machine for your collection and workload, and monitor the service logs and health status.

Keep the persistent data directory on storage with enough capacity for your retention needs, and maintain an independent backup. For reliability, review the downloaded Compose file and image choice before updates, especially if you need repeatable deployments. The supplied installation guidance does not specify hosting-provider prices, resource requirements, or a fixed release version, so those should be decided for your own environment.

Or skip the browser setup

If you need screenshots of pages in your ArchiveBox workflow, ScreenshotNeo offers a website screenshot API and MCP server. A single GET request can return an image or PDF. Its cleanup accepts cookie or consent banners like a visitor and removes more than 60 known consent platforms, newsletter popups, and chat widgets before capture; each cleanup step can be disabled. Bot checks, blank pages, timeouts, failed loads, and cache hits are not billed, with the page verdict and billing status included in response headers. AI agents can use its MCP server tools, including take_screenshot, get_page_info, and capture_pdf.

For the rest of this article’s DIY task—running ArchiveBox itself—use the Compose steps above. For a screenshot call, the following runnable cURL example saves a WebP capture:

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

See the ScreenshotNeo API documentation for the request options. The free plan includes 1,000 screenshots per month with no card; paid plans start at $5 for 3,000 screenshots. Sign up for ScreenshotNeo and get 1,000 screenshots a month free, with no card.

FAQ

Does this install use Docker Compose v1?

No. The current deployment instructions require Docker Compose v2 and use the docker compose command.

Where are my archived files stored?

The Compose setup uses the host-side ~/archivebox/data directory for persistent collection data.

Can I run ArchiveBox without opening the setup wizard?

The deployment guide documents optional ADMIN_USERNAME and ADMIN_PASSWORD environment variables for administrator creation. The wizard is the documented interactive first-run path.

Is port 5797 the host port?

It is the container listener port in the current deployment guide. ARCHIVEBOX_PORT can change the host port that maps to it.