ARTEMIS Installation and Setup
Install Packages
-
Make sure that your Ubuntu package sources are up-to-date:
sudo apt-get update
-
(For rootless installation look below) If not already installed, follow the instructions here to install the latest version of the docker tool for managing containers, and here to install the docker-compose tool for supporting multi-container Docker applications.
In production, we have used the following versions successfully:
$ docker -v Docker version 18.09.0, build 4d60db4 $ docker-compose -v docker-compose version 1.20.0, build ca8d3c6
-
If you would like to run docker without using sudo, please create a docker group, if not existing:
and then add the user to the docker group:sudo groupadd docker
For more instructions and potential debugging on this please consult this webpage.sudo usermod -aG docker $USER
-
Install ntp for time synchronization:
sudo apt-get install ntp
-
Install git for downloading ARTEMIS:
and then download ARTEMIS from github (if not already downloaded):sudo apt-get install git
git clone https://github.com/FORTH-ICS-INSPIRE/artemis
-
The docker-compose utility is configured to pull the latest stable released images that are built remotely on docker cloud. Run the following:
to trigger this.cd artemis docker-compose pull
No further installation/building actions are required on your side at this point.
Rootless Docker
You can follow instructions on how to install rootless docker here.
In our setup we used slirp4netns
as the network stack and instead of ports 80 and 443 we remapped to 8080 and 8433 for avoid the need of binding with sudo
.
You can change these values inside the docker-compose.yaml
:
ports:
# uncomment both lines for rootless
# - "8080:8080"
# - "8443:8443"
# comment both lines when running rootless
- "80:80"
- "443:443"
These changes should be sufficient to have artemis running rootless on https://localhost:8443
.
Setup Tool
-
Edit environment variables in
.env
file (especially the security-related variables); please check this docs page for more information on the env variables. -
It is important that before starting ARTEMIS, you should setup secure access to the web application (used to configure/control ARTEMIS and view its state), by editing the following file:
and adjusting the following parameters/environment variables related to the artemis_frontend:.env
and modifying the secrets for your own deployment (critical):ADMIN_PASS=admin1234 ADMIN_EMAIL=admin@admin.com MONGODB_USER=admin MONGODB_PASS=pass ARTEMIS_WEB_HOST=artemis.com # please adjust to your local server domain
Except for theJWT_SECRET_KEY HASURA_SECRET_KEY CSRF_SECRET API_KEY LDAP_BIND_SECRET
HASURA_SECRET_KEY
, which is a master password for the graphql queries, the other keys need to be randomly generated with the following command (generates 32 random bytes hexadecimal string):NOTE: For security reasons, we highly recommend randomizing these keys (no defaults), and using strong passwords. Be careful with special characters in these fields as some of them need to be escaped and other are passed as URI.openssl rand -hex 32
We suggest using HEX format or URL encoded passwords to avoid any issues.
-
Decouple your setup files (tool configurations) from the default ones (that are under version control), by doing the following in your local artemis directory:
The source mappings inmkdir -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
docker-compose.yaml
are already updated by default. Thelocal_configs
directory is NOT under version control. The same applies to:A sample folder structure for local_configs is the following:postgres-data-current postgres-data-backup mongo-data
$ 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
-
Setup
https
: the ARTEMIS web application supportshttps
by default to ensure secure access to the application. We use a nginx reverse proxy to terminate SSL connections before forwarding the requests to Flask. To configure your own (e.g., self-signed) certificates, please place in the following folder:the following files:local_configs/frontend/certs
If you want to use e.g., "let's encrypt" certificates you can do the following steps:cert.pem key.pem
-
edit the file:
according to your setup, and then run it with sudo (after making sure it is executable).other/lets_encrypt.sh
-
edit the nginx section of the file:
to include the following volume mappings instead of the default certs one (comment that one out):docker-compose.yaml
- /etc/letsencrypt/live/<domain>/fullchain.pem:/etc/nginx/certs/cert.pem - /etc/letsencrypt/live/<domain>/privkey.pem:/etc/nginx/certs/key.pem - /etc/letsencrypt/options-ssl-nginx.conf:/etc/nginx/options-ssl-nginx.conf - /etc/letsencrypt/ssl-dhparams.pem:/etc/nginx/ssl-dhparams.pem
-
edit the nginx configuration file:
to include the following lines:local_configs/frontend/nginx.conf
ssl_dhparam /etc/nginx/ssl-dhparams.pem; include /etc/nginx/options-ssl-nginx.conf;
Also, if you require selective access to the UI from certain IP ranges, please adjust and comment out the nginx ACL-related lines in:
NOTE: For security reasons, we highly recommend replacing the default certificates, as well as restricting access to the nginx server.local_configs/frontend/nginx.conf
-
-
Setup logging and access to ARTEMIS logs, by checking the corresponding docs page.
You do not need to modify any other setup files and variables for now.
Optional configurations
Optionally, you can enable daily backups by changing the DB_BACKUP
environment variable inside .env
to true:
DB_BACKUP=true
In order to restore a backed up DB: Please check Restoring DB from backup.
Furthermore, you can decide if you want to delete all old unwanted (non-hijack) BGP updates
by setting the DB_AUTOCLEAN
environment variable; this marks a time window (in hours)
in which ARTEMIS keeps benign BGP updates. E.g.,
DB_AUTOCLEAN=24