Upgrading ARTEMIS to a new version

Main steps

Before upgrading, we recommend that you ensure that there is a recent (at most a day old) backup db.tar of the database under postgres-data-backup. Then, do the following:

Make sure you have copied the default configs directories under local_configs and have updated the source volume mappings accordingly; check this file carefully for local_configs mappings. A sample folder structure for local_configs is the following:

$ tree local_configs
local_configs
├── backend
│   ├── autoconf-config.yaml
│   ├── config.yaml
│   ├── logging.yaml
│   └── redis.conf
├── frontend
│   ├── certs
│   │   ├── cert.pem
│   │   └── key.pem
│   └── nginx.conf
└── monitor
    ├── exabgp.conf
    └── logging.yaml

Deactivate current running instance:
```
docker-compose -f ... down
```
Stash any local changes that should not conflict with upstream
```
git stash
```
Checkout the master branch
```
git checkout master
```
Pull most recent code (including .env, versions, etc.)
```
git pull origin master
```

(Only if migrating to 2.0.0 or latest from older version)

mkdir -p local_configs && \
mkdir -p local_configs/backend && \
mkdir -p local_configs/monitor && \
mkdir -p local_configs/frontend && \
cp -rn backend-services/configs/* local_configs/backend && \
cp backend-services/configs/redis.conf local_configs/backend/redis.conf && \
cp -rn monitor-services/configs/* local_configs/monitor && \
cp -rn other/frontend/configs/* local_configs/frontend

The -n flag will prevent overwriting any local changes you have already made.

Re-apply local changes (if auto-merge fails, resolve any conflicts)
```
git stash pop
```
NOTE: when migrating to 2.0.0, the docker-compose.yaml file will undergo significant changes which you should accept from upstream! If needed, recheck the yaml file and make sure that the correct local-configs volume mappings are applied.
Make sure that you also do a
```
docker-compose -f ... pull
```
to ensure that you are not running an outdated version of the tool's containers.

You are all set! Now you can boot ARTEMIS (docker-compose -f ... up -d).

Notes

To work on a specific release the master code and the release version need to be compatible. Therefore, if you do not want to have access to the latest code, but work on a previous stable release, you need to do:

git checkout tags/<release_id>

instead of step 5. This will automatically set the SYSTEM_VERSION in the .env file to "release-XXXX", and sync the DB_VERSION. Always upgrade, never downgrade! A docker-compose ... pull will still be required.

Note that to avoid merge conflicts in general, we recommend decoupling your local configurations from the upstream changes. However, we would recommend keeping an eye out for any upstream changes that are related to best practices for the configuration files.

WARNING: If the change requires a DB upgrade (will be noted in the release), please check the next section before doing:

docker-compose -f ... up -d

OPTIONAL: If you want to change things at your local source code, and need to build your custom monitor and backend containers (instead of pre-built images), you can use the following lines instead of image: ... (for backend and monitor containers, respectively):

build: ./backend-services/<microservice>
build: ./monitor-services/<microservice>

Note also that you need to always map your volumes properly (e.g., ./backend-services/<microservice>:/root/...., etc.). Custom building can be triggered with:

docker-compose -f ... build

Also note that Kubernetes/helm upgrades may require a slightly different process, based on deployment upgrade. For more details please ping us on slack or describe your experience in a GitHub issue.

Migrating an existing DB to a new version

While developing ARTEMIS, we may also need to change the DB schema. In general, we aim to always remain backwards compatible; however you will probably not be able to run new code on an old schema. For this reason, we have developed an automated migration process that takes care of such migrations. To migrate to a new DB state that is in sync with the current code, simply execute the ARTEMIS version upgrade workflow (see previous section). If everything rolled down correctly (according to the logs), you will see that the migration process was successful and ARTEMIS will be able to start correctly with "up -d". If something fails, please contact the ARTEMIS team.