ar.ioar.io Documentation

Upgrading your gateway

Upgrade your gateway to each new release to get its fixes and security updates. Your indexed data is stored in the data/ directory on the host, not inside the containers, so upgrading keeps your data and indexing progress.

Before you start

  • Your gateway must have been set up from a git clone of the ar-io-node repository. If it wasn't, follow the installation instructions.
  • Find your current release in the release field of https://<your-gateway>/ar-io/info. A release ending in -pre means you run the develop branch; the steps below move you to main.
  • Read the release-specific steps for every release you are upgrading past, and the GitHub releases or CHANGELOG for new environment variables. New releases are also announced in the ar.io Discord.

Upgrade your gateway

Run these commands from your gateway's directory. On Windows, leave out sudo.

Pull the new release

git checkout main
git pull

Update .env

  • Add or change any variables the release notes ask for.
  • If you pin image tags in .env (CORE_IMAGE_TAG, ENVOY_IMAGE_TAG, OBSERVER_IMAGE_TAG and others), update them to the new release's values, or remove them to use the defaults in docker-compose.yaml. A pinned tag overrides the default, so a stale pin keeps the old image running.

Stop the gateway

sudo docker compose down

Start the gateway

sudo docker compose up -d

Docker pulls the images named in docker-compose.yaml, so you don't need --build.

If you normally start your gateway with -f files or --profile flags (for example -f docker-compose.yaml -f docker-compose.grafana.yaml, or --profile clickhouse), pass the same ones to down and up. Passing any -f stops Docker Compose from loading docker-compose.override.yaml automatically, so name it too if you use one.

Check the upgrade

Check that https://<your-gateway>/ar-io/info shows the new release, that every container is running (sudo docker compose ps), and that the core logs show no repeating errors (sudo docker compose logs -f core).

Free disk space (optional)

Old images stay on disk after an upgrade. To remove every image no container uses:

sudo docker image prune -a

Other Docker projects

This also removes unused images of any other Docker project on the machine.

Release-specific steps

Some releases need a step beyond the upgrade above. Do these when you upgrade to the release named, or past it. Each release's CHANGELOG entry has the full list of changes.

Release 88

  • Purge cached JSON wrappers. Before Release 88, a gateway could cache arweave.net's JSON description of a data item in place of the item, and then serve it with the wrong content type and hash. Observers report these as dataHashDigest and contentType mismatches. Release 88 fixes the fetch, but copies already cached keep being served until you purge them. A wrapped copy starts with {"accept-ranges". For each affected ID, call the new POST /ar-io/admin/invalidate-data, then purge any NGINX or CDN cache in front of the gateway. See Purging cached JSON wrappers.
  • Expect 503s for slow chunks. /chunk/<offset> now answers 503 with Retry-After: 5, not 404, when it couldn't fetch a chunk in time. Your dashboards will count these as 5xx errors.
  • Raise GATEWAYS_GQL_MAX_HOPS on a federation-only gateway. GraphQL queries fanned out to GATEWAYS_GQL_URLS now stop after GATEWAYS_GQL_MAX_HOPS gateways (default 2). If your gateway sets GATEWAYS_GQL_INCLUDE_LOCAL=false and other gateways query it through one more hop, raise it, for example to 3.

Release 87

  • Upgrade gateways that take parquet-l1 bands. Gateways that subscribe to parquet-l1 need Release 87 to take bands published in the new l1-4 layout. With l1-4 bands, L1_BAND_IMPORT_ALLOW_UNVERIFIED is no longer needed.
  • Remove INDEX_EXPORT_L1_WITNESS_MAX_MISSING from .env if you set it. The setting is gone.

Release 86

  • Upgrade now: this is an urgent security release. It moves the core image from Node.js 20 to 22.23.4, and the default observer image to Node.js 22.23.4, to fix a remote code execution bug in Node's Brotli decoder (CVE-2026-111497) and two TLS hostname-check bypasses. Upgrade both images.
  • Update a pinned OBSERVER_IMAGE_TAG or CORE_IMAGE_TAG. A tag you set in .env overrides the new default and keeps the vulnerable image. Update it, or remove it.
  • Use Node.js 22 if you run from source. The repository's .nvmrc now names Node.js 22.
  • Drop a Brotli workaround. If you stopped Brotli decoding with a NODE_OPTIONS=--require shim, you can remove it once you run the new image.
  • L1 band imports are stricter. With L1_BAND_IMPORT_ENABLED=true, the gateway refuses l1-3 bands below height 2,000,000 unless you set L1_BAND_IMPORT_ALLOW_UNVERIFIED=true. Release 87's l1-4 bands don't need it.
  • Publishers of parquet-l2 indexes: upgrade subscribers first. Every band is now built in the l2-2 layout, and a subscriber older than Release 86 refuses l2-2 bands.

Release 85

  • Index Sharing is on by default. A plain docker compose up -d now also starts the Index Sharing sidecar and its torrent engine. Your gateway subscribes to turbo-gateway.com's root transaction index, downloads about 22 GB of bands, searches them first for root transaction and offset lookups, and seeds them to other gateways. Before upgrading:
    • Keep at least 64 GiB free on the filesystem that holds data/indexes (INDEX_SWARM_MAX_DISK_BYTES, 64 GiB by default with the default subscription), or set a lower budget.
    • Allow about 0.4 GB more memory: about 90 MB for the sidecar and 300 MB for the engine.
    • Make sure nothing else on the host uses port 6881 (the engine's peer port, TCP and UDP) or port 6969 on 127.0.0.1 (the tracker, which the sidecar publishes on the loopback address only). Neither container starts without its port. Opening 6881 to the internet is recommended, not required.
    • On metered bandwidth, lower INDEX_SWARM_UPLOAD_LIMIT_BYTES_PER_SEC (10 MB/s by default) and INDEX_SWARM_UPLOAD_DAILY_LIMIT_BYTES (100 GB a day).
    • To opt out, set INDEX_SWARM_SUBSCRIBE=[] in .env before you upgrade. Bands already installed stay in use. On Release 85 they are still seeded; from Release 86 opting out also stops seeding them, and the files are kept. See Turning it off.
    • If you set up Index Sharing on Release 84, your settings still apply: an INDEX_SWARM_SUBSCRIBE, INDEX_SWARM_ENGINE_AUTH, INDEX_SWARM_MAX_DISK_BYTES, CDB64_ROOT_TX_INDEX_SOURCES or ROOT_TX_LOOKUP_ORDER you set is used unchanged, and installed bands are kept, not downloaded again. A subscription you set has no disk cap unless INDEX_SWARM_MAX_DISK_BYTES is set; the Release 84 setup script set one.
    • If your sidecar ran over HTTP only on Release 84, it now gets the torrent engine too, with a generated password. To keep HTTP only, see HTTP only.
  • Range misses now fill the cache in the background. BACKGROUND_CACHE_RANGE_MAX_SIZE now defaults to 10 GiB (it was 0, off) and BACKGROUND_CACHE_RANGE_CONCURRENCY to 4 (it was 1). A range request for an uncached item fetches only the range, and then the whole item, up to 10 GiB, is fetched into the cache in the background. Expect the data cache to grow faster with items read by range, such as video, SQLite or Parquet files. To keep the old behaviour, set BACKGROUND_CACHE_RANGE_MAX_SIZE=0.
  • JSON is served without an added charset. A JSON item is now sent with the Content-Type it was uploaded with, not application/json; charset=utf-8. Responses an NGINX or CDN cache already holds keep the old header until they expire or are purged.
  • Drop tip-5.arweave.xyz from your own chunk node lists. Release 85 removed it from the default preferred chunk nodes because it stopped answering. If you set PREFERRED_CHUNK_GET_NODE_URLS or PREFERRED_CHUNK_POST_NODE_URLS, remove it there too.
  • Upgrade the Envoy image with core. Peers now announce to an Index Sharing publisher's tracker through the gateway, at /ar-io/indexes/announce, and Envoy routes that path. An older Envoy passes it to core, which answers 404, so every announce fails without an error. If you set ENVOY_IMAGE_TAG in .env, update it too.
  • Index Sharing services run the core image. The index-swarm sidecar, the engine's setup step (index-swarm-engine-init) and index-export run the core image (CORE_IMAGE_TAG, or INDEX_EXPORT_IMAGE_TAG for index-export when set), so they move to the new image with core when you pass your usual -f files and --profile flags. The sidecar and the engine start by default; index-export is in a compose profile that is off unless you name it.
  • Torrent publishers: move peers to the gateway's tracker route. The setup script keeps an existing INDEX_SWARM_TRACKERS, so a publisher set up on Release 84 still announces to the tracker's own port (6969), which must stay reachable. From Release 85 that port is published on 127.0.0.1 only. Until you move peers to the gateway's route, set INDEX_SWARM_TRACKER_HOST_IP=0.0.0.0 in .env before you upgrade, or peers can't reach the tracker. To announce through the gateway instead, set INDEX_SWARM_TRACKERS=https://<your-gateway>/ar-io/indexes/announce and restart the sidecar. On its next scan it rebuilds each band's .torrent with the new tracker. The infohashes don't change, since trackers sit outside the info dictionary.
  • Update a pinned OBSERVER_IMAGE_TAG. Release 85's observer runs the offset checks on every gateway each epoch, including yours: a gateway fails when all 4 sampled offsets fail, so upgrade core with the observer. A tag you set in .env overrides the compose default, so update it there.
  • Purge gzip bodies cached before the upgrade. Before Release 85, a gateway could serve a gzip-compressed upload decoded, either still labelled Content-Encoding: gzip or without the header. Bodies an NGINX proxy_cache stored before the upgrade keep the wrong body until they expire or are purged. Cache bypass header shows how to refresh one. When your gateway finds a decoded copy in its own cache, it logs a warning and counts it in served_content_encoding_dropped_total.
  • Don't trust gateways older than the gzip fix. A gateway older than Release 85 can serve a gzip-compressed upload decoded. Release 85 refuses those bodies when the response's headers give them away, but a decoded body sent with neither Content-Encoding nor the tag headers can't be told apart. Don't list such gateways in TRUSTED_GATEWAYS_URLS or TRUSTED_GATEWAY_URL.

Getting help

If something doesn't work after an upgrade, see Troubleshooting or ask in the ar.io community Discord.

How is this guide?