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

Full Upgrade Process

Pull Latest Changes

Navigate to your cloned repository directory and execute:

git pull

Shut Down Docker

Stop your gateway:

sudo docker compose down -v

docker compose down -v

Check for New Environment Variables

Read the update release change logs and community announcements to see if the new version includes any new environmental variables that you should set before restarting your gateway.

Restart the Gateway

Start your gateway with the new version:

sudo docker compose up -d

docker compose up -d

You don't need the --build flag: Docker uses the image named in docker-compose.yaml.

Docker Pruning (Optional)

It's a good practice to clean up unused Docker resources after shutting down your gateway.

Important

This will erase all inactive docker containers on your machine. If you use docker for anything beyond running a gateway be extremely careful using this command.

Shut Down Gateway

First, stop your gateway:

sudo docker compose down -v

docker compose down -v

Prune Docker System

Clean up unused Docker resources:

sudo docker system prune

docker system prune

Restart Gateway

Start your gateway:

sudo docker compose up -d

docker compose up -d

Checking for New Environment Variables

New gateway releases may introduce new environment variables that you need to configure.

Review Release Notes

Check the release notes and community announcements for any new environment variables:

Review the GitHub releases
Check the ar.io Discord for announcements
Look for changes in the .env.example file

Update Your .env File

Add any new environment variables to your .env file:

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

Restart Gateway

Restart your gateway to apply the new environment variables:

sudo docker compose up -d

docker compose up -d

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.

How is this guide?

Upgrading your Gateway

On this page