Upgrading ARTEMIS to a new version
Before upgrading, we recommend that you ensure that there is a recent (at most a day old) backup
db.tar of the database under
Then, do the following:
Make sure you have copied the default configs directories under
local_configsand have updated the source volume mappings accordingly; check this file carefully for
local_configsmappings. A sample folder structure for
local_configsis the following:
$ tree local_configs local_configs ├── backend │ ├── autoconf-config.yaml │ ├── config.yaml │ ├── logging.yaml │ └── redis.conf ├── frontend │ ├── certs │ │ ├── cert.pem │ │ └── key.pem │ ├── config.py │ ├── __init__.py │ ├── logging.yaml │ ├── nginx.conf │ └── webapp.cfg └── monitor ├── exabgp.conf └── logging.yaml
Deactivate current running instance:
docker-compose -f ... down
Stash any local changes that should not conflict with upstream
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)
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 frontend/webapp/configs/* local_configs/frontend
-nflag 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.yamlfile will undergo significant changes which you should accept from upstream! If needed, recheck the yaml file and make sure that the correct
local-configsvolume mappings are applied.
Make sure that you also do ato ensure that you are not running an outdated version of the tool's containers.
docker-compose -f ... pull
You are all set! Now you can boot ARTEMIS (
docker-compose -f ... up -d).
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>
docker-compose ... pullwill 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
frontend and backend containers (instead of pre-built images), you can use the following lines instead of
image: ... (for backend, frontend and monitor containers, respectively):
build: ./backend-services/<microservice> build: ./monitor-services/<microservice> build: ./frontend
./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.