Upgrading your Gateway

Upgrade your ar.io gateway to each new release to get its fixes and security updates. Indexed data lives outside Docker, so neither upgrading the gateway nor pruning Docker erases your data or progress.

Prerequisites

• Your Gateway should have been cloned using git. If you haven't, follow the installation instructions.

Checking your Release Number

Effective with release 3, you can view the currently implemented release on any gateway by visiting https://<gateway>/ar-io/info in a browser. Be sure to replace <gateway> with the domain of the gateway you are checking.

If the release number displayed includes -pre it means that your gateway is using the develop branch of the github repo for the gateway code. Follow steps in our troubleshooting guide to switch over to the more stable main branch.

Announcements will be made in our discord server showing each new release.

Upgrade Process

git pull

sudo docker compose down -v

docker compose down -v

sudo docker compose up -d

docker compose up -d

sudo docker compose down -v

docker compose down -v

sudo docker system prune

docker system prune

sudo docker compose up -d

docker compose up -d

# Example: Add new environment variables
NEW_FEATURE_ENABLED=true
NEW_CONFIG_VALUE=default_value

sudo docker compose up -d

docker compose up -d

Release-Specific Steps

Some releases need a step beyond pulling and restarting. Do these when you upgrade to the release named, or past it.

Release 85

• Index Sharing is on by default. After the upgrade, a plain docker compose up -d 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: the sidecar about 90 MB, the engine about 300 MB.
  • Make sure nothing else on the host holds port 6881 (the engine's peer port, TCP and UDP) or 6969 on 127.0.0.1 (the tracker's port, which the sidecar publishes on the loopback address only): either container won't start 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 that are already installed stay in use and seeded; see Turning It Off.
  • If you set up Index Sharing on Release 84, your settings in .env 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 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 now 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. 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 removes 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 that route is Envoy's. An older Envoy passes the path to core, which answers 404, so every announce fails without an error. If you set ENVOY_IMAGE_TAG in .env, update it too.
• Use the same -f files and --profile flags. The index-swarm sidecar, the torrent 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). From Release 85 the sidecar and the engine start by default; index-export is still in a compose profile that is off unless you name it. The torrent engine itself is qBittorrent's image. Pass the same -f files and --profile flags you start them with, so they move to the new core image along with core. Passing -f at all turns off loading docker-compose.override.yaml automatically, so name every compose file you normally use.
• Publishers of torrents: 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 open. From Release 85 that port is published on 127.0.0.1 only, so 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 moves the default observer image to c5e98ddc, which runs the offset checks on every gateway each epoch. Your own gateway is checked too: 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 force-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 that fix (#964, first released in 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.

That's it! Your ar.io Gateway is now upgraded to the latest version. Ensure to test and verify that everything is functioning as expected. If you encounter any issues, reach out to the ar.io community for assistance.