Upgrading your Gateway

To ensure the optimal performance and security of your AR.IO Gateway, it's essential to regularly upgrade to the latest version. Notably, indexed data resides separate from Docker. As a result, neither upgrading the Gateway nor pruning Docker will erase your data or progress. Here's how you can perform the upgrade:

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.

Quick Start

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

Restart Gateway

Start your gateway with the new version:

sudo docker compose up -d

docker compose up -d

Release #3 Note

Effective with Release #3, it is no longer required to include the --build flag when starting your gateway. Docker will automatically build using the image specified in the docker-compose.yaml file.

Detailed 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

Release #3 Note

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