How to Update an ArchiveBox Docker Installation Without Losing Archives

To update ArchiveBox in Docker without losing archives, keep the existing collection mounted at /data, stop every service that can write to it, back up the complete collection and relevant configuration, then update the image and run only the migrations required by the releases you are crossing. Verify old snapshots and a new capture before removing the backup. Never use docker compose down -v as part of an upgrade.

ArchiveBox stores its collection in persistent data, separate from the container image. If a replacement container mounts a different host directory or volume, it can look like an empty installation even though the old archives still exist elsewhere. [ArchiveBox Docker deployment guidance] [ArchiveBox installation and upgrade wiki]

1. Identify your installation before changing it

Run commands from the directory containing the active Compose file. Record the current image and tag, service names, ports, environment overrides, and the exact host directory or named volume mounted at /data. Also note any separate scheduler, Sonic service, browser personas, or custom configuration. These details determine which instructions apply.

docker compose ps

docker compose config

docker compose images

Inspect the rendered Compose configuration for the service that runs ArchiveBox and its /data mount. Treat the output of docker compose config as sensitive if it contains secrets. The official example uses a bind mount such as ./data:/data, but your existing installation may use a different path or named volume. Do not change that mapping by copying an example blindly. [ArchiveBox Docker deployment guidance] [Official Compose example]

Write down the current and target versions and list every release between them. Read the upgrade notes for each version you skip as well as the target release. ArchiveBox’s general upgrade instructions and release-specific migration notes have differed; an init step is not a universal substitute for a separately documented filesystem migration. [ArchiveBox upgrade guidance] [ArchiveBox release notes]

2. Stop writers and back up the whole collection

Stop the complete stack, including any scheduler or separate search service that might write to or depend on the collection. Ensure no ArchiveBox job is running while you copy files. Then make a backup of the entire collection directory, plus the Compose file and relevant configuration. Include browser personas if your deployment uses them. A database-only copy is not sufficient: the saved archive files and configuration matter too. [ArchiveBox Docker deployment guidance] [ArchiveBox release notes]

# From the active Compose project directory:
docker compose down

# Example only: replace ./data and ./backup with the paths you verified.
# The destination should have enough space for the complete collection.
cp -a ./data ./backup/archivebox-data-before-upgrade
cp -a ./docker-compose.yml ./backup/docker-compose.yml.before-upgrade

If your data lives in a named volume, back up that volume using your established Docker backup procedure rather than copying a nonexistent host directory. If a separate service stores personas or other required state outside the collection, back that up too. Keep the pre-upgrade copy until the upgraded instance passes the checks below. ArchiveBox explicitly warns against docker compose down -v during an upgrade because it removes volumes. [ArchiveBox Docker deployment guidance]

3. Update the image while preserving the data mount

Edit the existing Compose file only as needed for the selected release. Preserve the verified data mount, ports, and intentional environment settings. Select a tag compatible with your upgrade path. ArchiveBox’s current deployment examples use a development image, while latest follows stable; do not replace a stable image with dev unless that is the release you intend to run. Published versions, commit tags, and image digests can be used to pin an image. [ArchiveBox Docker deployment guidance]

# Pull the image selected in your Compose file.
docker compose pull

# Start and wait for health when the configured services support it.
docker compose up -d --wait --remove-orphans

The commands above illustrate the image and startup stage; they do not replace a release’s migration instructions. Some upgrades require running migration commands before the long-running service is started, or require a specific sequence. Follow the notes for the exact source-to-target version jump.

4. Run the migration required by your release path

The generic ArchiveBox upgrade wiki instructs operators to upgrade the collection with archivebox init and check its status. Specific releases may add or change steps. For example, the cited 0.9.x transition notes document running init and then update --migrate-only. Use this sequence only if it matches the release guidance for your upgrade; it is not a universal recipe. The migration can take minutes to hours depending on database size, so allow enough time and do not interrupt it. [ArchiveBox upgrade guidance] [ArchiveBox release notes]

# Example for the documented 0.9.x migration path only:
docker compose run archivebox init
docker compose run archivebox update --migrate-only
docker compose down --remove-orphans
docker compose up -d

Here archivebox is the Compose service name in the example notes. If your service has another name, substitute that name. Do not append -v to the down command. For other version jumps, run only the commands their release notes specify; do not combine unrelated instructions from different eras of the project.

Legacy Sonic deployments

Apply this section only if your old installation used Sonic. The current Docker deployment guidance tells affected older installations to stop their scheduler and Sonic services, remove legacy SEARCH_BACKEND_HOST_NAME=sonic or SEARCH_BACKEND_SONIC_HOST_NAME=sonic settings from the environment and saved configuration, and retain a backup of the old Sonic index. Rebuild the current index with update --index-only if needed. These changes are not required for an installation that never used those settings. [ArchiveBox Docker deployment guidance]

5. Verify the upgraded collection before deleting the backup

Check service health and the ArchiveBox version, then inspect collection status for errors, corruption, or orphaned snapshots. Log in, open at least one known old snapshot, and create a new test capture. If you had schedules, check that they still exist and avoid recreating them twice.

docker compose ps
docker compose logs --tail=200 archivebox
docker compose exec archivebox archivebox version
docker compose exec archivebox archivebox status
docker compose exec archivebox archivebox schedule --show

Replace archivebox in these commands if your Compose service has a different name. The schedule command is useful for checking schedules in deployments where it applies. Confirm a newly captured page appears alongside older snapshots. Keep the backup until these checks are satisfactory. [ArchiveBox Docker deployment guidance] [ArchiveBox upgrade guidance]

Plain Docker instead of Compose

With plain Docker, preserve the same host collection directory mounted at /data. Stop the old container before copying the collection, pull the chosen target image, run the release-required collection initialization or migration command against that same mount, and start the replacement container with the existing port, environment, and volume settings. The ArchiveBox upgrade guide includes archivebox init; consult the release notes for any additional migration. A different host path will expose an empty directory to the new container, not migrate your archives. [ArchiveBox upgrade guidance] [ArchiveBox Docker deployment guidance]

# Adapt container name, image tag, host data path, and ports to your setup.
docker stop archivebox
docker cp archivebox:/data ./archivebox-data-before-upgrade

docker pull archivebox/archivebox:YOUR_TARGET_TAG

# Example migration invocation against the same persistent host directory:
docker run --rm \
  -v /absolute/path/to/archivebox-data:/data \
  archivebox/archivebox:YOUR_TARGET_TAG \
  init

# Recreate the service with the same /data mount and settings used before.

The docker cp line is only suitable when the container’s /data contains the collection and the destination has adequate space; for bind mounts or named volumes, back up the underlying storage with your normal procedure. The final server creation command depends on your existing run options, so retain them rather than guessing new settings.

Troubleshooting

Symptom	Likely cause	What to do
The upgraded UI looks empty	The new container uses a different host path or volume for `/data`.	Stop it and compare the mount in the rendered Compose config with the recorded old mount. Restore the original mapping; do not initialize over the wrong directory.
Compose reports that the service is unhealthy or will not start	A migration is incomplete, a setting changed, or a dependency/service was omitted.	Read `docker compose logs`, check the target release notes and required services, then run only the documented migration sequence.
`archivebox init` succeeds but snapshots are missing or status is wrong	The upgrade path may require an additional migration, or the wrong collection was mounted.	Verify the mount first; compare current and target versions and check every intervening release note for extra steps such as `update --migrate-only`.
Search fails after an upgrade from a Sonic setup	Legacy Sonic host settings or services remain in the configuration.	Follow the migration guidance for older Sonic deployments, remove the specified obsolete settings, retain the old index backup, and rebuild the index if required.
The migration appears stuck	A large collection can make a database migration take a long time.	Inspect logs and allow the release-documented migration to finish. Do not start another migration concurrently or delete the pre-upgrade backup.
Old snapshots open, but new captures fail	The server may be running while a browser dependency, environment setting, or related service is misconfigured.	Check service logs and the release’s deployment requirements, then test a new capture after resolving the reported issue.
A rollback seems to lose recent work	The backup is a point-in-time copy made before the upgrade.	Stop writers before restoring the pre-upgrade collection. Treat captures made after that backup separately; do not merge database and archive files casually.

Performance, reliability, and storage considerations

Migration duration: Database migrations can take minutes to hours depending on database size, according to the cited 0.9.x release notes. Treat this as a broad project statement, not a duration guarantee for your collection.
Disk space: A full rollback copy needs room for the database and archived files, plus any separately stored configuration or personas. Check destination capacity before copying.
Consistency: Stop schedulers and other writers before copying. A backup taken while jobs are writing may not represent one consistent collection state.
Reproducibility: Record and pin the intended image tag or digest and keep the pre-upgrade Compose file with the backup. This makes it clearer which image and mount were used.
Rollback: Keep the old image reference and full pre-upgrade data copy. If verification fails, stop the upgraded stack and restore using the prior configuration and collection together, following any version-specific rollback guidance.

Or skip the browser setup

If your workflow also needs screenshots of web pages, ScreenshotNeo provides a website screenshot API and MCP server. It does not update or back up ArchiveBox; it can handle the separate task of capturing a page as an image or PDF. Send one GET request with the target URL. See the ScreenshotNeo API documentation for parameters and options.

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}`);
if (!res.ok) throw new Error(`Screenshot request failed: ${res.status}`);
const fs = await import('node:fs/promises');
await fs.writeFile('shot.webp', Buffer.from(await res.arrayBuffer()));

Cookie and consent banners are accepted or removed before capture; more than 60 known consent platforms, newsletter popups, and chat widgets are covered, and each step can be turned off.
Bot checks, blank pages, timeouts, failed loads, and cache hits cost nothing; response headers report the page verdict and billing status.
An MCP server provides take_screenshot, get_page_info, and capture_pdf tools for Claude, Cursor, and other MCP clients.
The Free plan includes 1,000 screenshots per month with no card. Paid plans start at $5 for 3,000 screenshots; every feature is on every plan.

FAQ

Will pulling a new Docker image delete my archives?

Replacing an image does not by itself remove a collection stored in a persistent host mount or volume. Data can appear missing if the replacement points at a different /data location, and removing a volume with down -v can delete it.

Can I skip the backup if I use a named volume?

No. A named volume is persistent storage, but it is not a backup. Make a separate copy of the complete collection and relevant configuration before migration.

Should every update run `archivebox update --migrate-only`?

No. That command is required for the cited 0.9.x transition; use it only when the release notes for your version jump call for it.

When is it safe to remove the old backup?

After the service is healthy, status checks pass, known old snapshots open, schedules are accounted for where relevant, and a new capture succeeds.