Skip to content

Latest commit

 

History

History
84 lines (67 loc) · 4.91 KB

upgrading-orion.md

File metadata and controls

84 lines (67 loc) · 4.91 KB

Upgrading Orion

You'll usually be upgrading Orion together with Atlas in case there is a new release and you would like to take advantage of the new features and bug fixes introduced in the new version.

Staying up-to-date with the latest releases

Orion follows the release process described in Releasing Orion tutorial inside the Orion Developer Guide.

You can check the list of all Orion releases on the GitHub releases page of Orion repository.

The changes introduced in each of those releases are also described in the CHANGELOG.

On the Atlas side, you can check the list of releases here and the CHANGELOG can be found here.

Always make sure the versions of Orion and Atlas you're planing to upgrade to are compatible with each other.

Typical upgrade process (For Breaking Changes)

  1. Turn on the kill switch (maintenance mode). This will prevent the users from interactig with the Gateway during the upgrade, as this could have undesired consequences (for example, due to processor not being fully synced). To do that you should execute setKillSwitch(isKilled: true) operator mutation using Orion's GraphQL API (you need to be authenticated as Operator first).

  2. Make sure to update the .env file in case there are any new environment variables introduced or a change in some existing environment variable value is required. This should be mentioned in the CHANGELOG and/or the release notes.

  3. Backup the databse before the upgrade. You can do that by executing the following command on the production server:

    docker exec orion_db pg_dumpall -U postgres -p 23798 > "orion-production-$(date '+%Y-%m-%d').bak"

    Make sure the backup file was successfully created in the current directory.

  4. Stop the processor and create Offchain data export file:

    docker-compose stop orion_processor
docker-compose run --rm orion_processor npm run offchain-state:export

    Make sure the export file was created successfully under ./db/export/export.json

  5. Download the latest Orion docker image:

    docker tag joystream/orion:latest joystream/orion:previous
docker pull joystream/orion:latest

  6. Bring down all of the currently running Orion services:

    docker-compose down -v

  7. Start the new Orion services:

    docker-compose up -d

  8. Wait for the Orion processor to catch up with the Joystream blockchain before disabling the kill switch. You can follow the processor logs using:

    docker logs -f --tail 10 orion_processor

    You can also check the logs of other docker services, ie. orion_graphql-api, orion_auth-api and orion_db to make sure they are running as expected.

  9. After the processor is synced, you can run some test queries on https://query.mygateway.com/graphql (first you'll need to authenticate, for example through https://auth.mygateway.com/playground) to make sure the new version is working as expected.

  10. Once you're confident that the release was successful, disable the kill switch by executing setKillSwitch(isKilled: false) operator mutation using Orion's GraphQL API.

Restoring the previous version

In case something goes wrong during the upgrade, you can restore the database from backup created in step 2. and switch back to the previous version of Orion by executing the following commands:

    # Bring down the Orion services
    docker-compose down -v
    # Remove the export.json file (if exists) as it may interfere with the restore process
    rm ./db/export/export.json
    # Switch back to the previous version of joystream/orion docker image
    docker tag joystream/orion:previous joystream/orion:latest
    # Start the orion-db service
    docker-compose up -d orion_db
    # Copy the backup file to the orion-db container
    # Replace the YYYY-mm-dd with the date of the backup you wish to restore
    docker cp "orion-production-YYYY-mm-dd.bak" orion_db:/tmp/orion-production.bak
    # Restore the database
    docker exec orion_db psql -f /tmp/orion-production.bak -U postgres -p 23798 postgres
    # Bring up the Orion services
    docker-compose up -d

Upgrade Process (For Non-breaking Changes)

The non breaking changes include examples such as adding nullable field to the entity or making the change to the mappings that does not require processor re-syncing. In this case, you just new to restart the services to deploy new changes:

# Restart the Orion services to apply latest code changes
docker restart orion_processor orion_graphql-server orion_auth-api