Installation

Requirements: docker and docker-compose

To build and deploy actinia, run

git clone https://github.com/actinia-org/actinia-docker.git cd actinia-docker docker-compose -f docker-compose.yml up Now you have a running actinia instance locally! Check with curl http://127.0.0.1:8088/api/v3/version

• Having trouble? See How to fix common startup errors below.
• Want to start developing? Look for Local dev-setup with docker below.
• For production deployment, see Production deployment below.

On startup, some GRASS GIS projects are created by default but they are still empty. How to get some geodata to start processing, see in Testing GRASS GIS inside a container below.

General

This repository is a set of Dockerimages and docker-compose configs.

Ready to use Dockerimages are available at https://hub.docker.com/r/mundialis/actinia-core

actinia-alpine * build and pushed to mundialis/actinia * includes actinia-plugins * includes GRASS GIS addons * includes snappy

actinia-dev * useful for local dev setup for actinia and plugins

actinia-prod * example configuration for production deployment (overwrites default config)

actinia-ubuntu * Ubuntu Dockerimage with snappy and some actinia plugins

actinia-data * Shared by all containers, contains common configs and data

How to fix common startup errors

• if a valkey db is running locally this will fail. Run and try again: /etc/init.d/valkey-server stop
• if you see an error like "max virtual memory areas vm.maxmapcount [65530] is too low, increase to at least [262144]", run sudo sysctl -w vm.max_map_count=262144 this is only valid on runtime. To change permanently, set vm.maxmapcount in /etc/sysctl.conf

Local dev-setup with docker

For a dev setup where no actinia plugins are involved, simply follow the steps explained in actinia-core directly. Instead of from actinia_core/docker run the steps from actinia-docker.

Local dev-setup for actinia-core plugins

For a local dev setup for actinia-core and actinia-core plugins (eg. actinia-actinia-metadata-plugin or actinia-module-plugin), uninstall them in actinia-dev/Dockerfile (see outcommented code) and mount local checkouts in the container via docker-compose-dev.yml file (also see outcommented code). Build and run like described below and rebuild from your mounted source code: ``` docker compose -f docker-compose-dev.yml build docker compose -f docker-compose-dev.yml run --rm --service-ports --entrypoint sh actinia

(cd /src/actinia_core && python3 setup.py install)

for installing plugins, following two commands have to be executed additionally

Note: the second one have to be modified, depending on the module

export SETUPTOOLSSCMPRETEND_VERSION=0.0.0 git config --global --add safe.directory /src/actinia-module-plugin

(cd /src/actinia-metadata-plugin && python3 setup.py install) (cd /src/actinia-module-plugin && python3 setup.py install)

you can also run tests here, eg.

(cd /src/actinia-module-plugin && python3 setup.py test)

Includes creation of actinia-gdi user

sh /src/start.sh

gunicorn -b 0.0.0.0:8088 -w 1 --access-logfile=- -k gthread actiniacore.main:flaskapp

```

To avoid cache problems, remove the packaged actiniacore (already done in Dockerfile) ``` pip3 uninstall actiniacore -y If you have other problems with cache, run python3 setup.py clean --all ```

Local dev-setup for actinia-core plugins with vscode

For a local dev setup for actinia-core and actinia-core plugins with vscode, you need to have the actinia repositories checked out next to each other, e.g. repos/actinia/ ├── actinia-api ├── actinia_core ├── actinia-docker ├── actinia-metadata-plugin ├── actinia-module-plugin Then move the .vscode folder from this repository one level up and open the whole actinia folder as workspace in vscode. This can be done by eg. typing code $PATH_TO_MY_ACTINIA_CHECKOUTS in a terminal. Then press F5 and after a few seconds, a browser window should be opened pointing to the version endpoint. For debugging tips, read the docs.

Local dev-setup for actinia-core with Keycloak

For deployment change passwords in .env file!

Add to the actinia.cfg the configuration for Keycloak: [KEYCLOAK] config_path = /etc/default/keycloak.json group_prefix = /actinia-user/ where the config_path is the file to the Keycloak OIDC JSON from the actinia client in Keykloak (for the DEV setup it is in actinia-dev/keycloak.json).

Then you can start the docker DEV setup as in local dev-setup with docker. ``` docker compose -f docker-compose-dev.yml build

start first postgis

docker compose -f docker-compose-dev.yml up -d postgis

then start keycloak

docker compose -f docker-compose-dev.yml up -d keycloak ```

By first Keycloak setup you have to load the inital keycloak data: 1. Problem: accessible_datasets and accessible_modules can get to long so that org.postgresql.util.PSQLException: ERROR: value too long for type character varying(255) occurs. To fix this you can change in PostgreSQL the value type to text: ``` docker exec -it actinia-dockerpostgis1 sh

psql -h localhost -U keycloak
\c keycloak
\d user_attribute
ALTER TABLE user_attribute ALTER COLUMN value type text;
```
After the change you have to restart keycloak
```
docker restart actinia-docker_keycloak_1
```

1. Import inital Keycloak data: ``` docker cp ./actinia-keycloak/initdata/keycloakexportdev.json actinia-dockerkeycloak1:/tmp/keycloakexport.json

docker exec -it actinia-dockerkeycloak1 /opt/jboss/keycloak/bin/standalone.sh -Djboss.socket.binding.port-offset=100 -Dkeycloak.migration.action=import -Dkeycloak.migration.provider=singleFile -Dkeycloak.migration.usersExportStrategy=REALMFILE -Dkeycloak.migration.file=/tmp/keycloakexport.json Wait until finished (look out for Import finished successfully in the logs) and exit the container. After the change you have to restart keycloak docker restart actinia-dockerkeycloak1 ``` 3. now you can access keycloak via http://localhost:8080 (admin:keycloak) * Admin console: http://localhost:8080/auth/admin * User console: http://localhost:8080/auth/realms/testrealm/account/#/

Then you can start actinia: docker-compose -f docker-compose-dev.yml run --rm --service-ports --entrypoint sh actinia python3 setup.py install sh /src/start.sh And test it, e.g. with getting the token via Python3: ```python3 from keycloak import KeycloakOpenID

keycloakurl = "http://localhost:8080/auth/" realm = "actinia-realm" clientid = "actinia-client" clientsecretkey = "KCXeHuJCLfd8qIhwIYkWZLrkauzBkLAb"

keycloakopenid = KeycloakOpenID(serverurl=keycloakurl, clientid=clientid, realmname=realm, clientsecretkey=clientsecretkey)

superadmin

user = "actinia-superadmin" pw = "actinia-superadmin"

token = keycloakopenid.token(user, pw) print(token["accesstoken"]) Request actinia via Keycloak token: TOKEN=xxx curl -H 'Accept: application/json' -H "Authorization: Bearer ${TOKEN}" http://localhost:8088/api/v3/version | jq

request mapsets

curl -H 'Accept: application/json' -H "Authorization: Bearer ${TOKEN}" http://localhost:8088/api/v3/projects/ncspm08/mapsets | jq ```

Testing GRASS GIS inside a container

See this README for more information.

Production deployment

To run actiniacore in production systems, you can use the docker-compose-prod.yml. Please change before the default valkey password in valkeydata/config/.valkey and inside the actinia.cfg. Also incomment the build block in the docker-compose.yml. Additional change the keycloak and postgis passwords in .env file.

To start the server, run:

docker-compose -f docker-compose.yml build docker-compose -f docker-compose.yml up -d Then actinia runs at 'http://127.0.0.1:8088' and depending on your server settings might be accessible from outside. Because of this the start.sh is overwritten to not create any user to avoid security vulnerability. You will have to use a clean key-value database to avoid stored actinia credentials from previous runs. You have to create the user by yourself by using the built-in actinia-user cli. Please change below username (-u) and password (-w): ```

list help about the cli tool:

docker-compose -f docker-compose.yml exec actinia \ actinia-user --help

create a user and grant permissions to mapsets:

docker-compose -f docker-compose.yml exec actinia \ actinia-user create -u actinia-core -w actinia-core -r user -g user -c 100000000 -n 1000 -t 6000 docker-compose -f docker-compose.yml exec actinia \ actinia-user update -u actinia-core -d ncspm08/PERMANENT ``` Read more about user roles here: https://actinia.mundialis.de/tutorial/actinia_concepts.html#user-user-roles-and-user-groups

Testing the actinia server

After deployment, you should be able to access the endpoints.

Examples:

• https://actinia.mundialis.de/latest/version
• https://actinia.mundialis.de/latest/health_check
• requires authorization (actinia user):
  • https://actinia.mundialis.de/api/v3/projects

Cloud deployment with multiple actinia_core instances

For cloud deployment, you can use the docker-swarm.sh script as a starting point.

Shutdown current actinia swarm: docker stack rm actinia_swarm docker swarm leave --force Start new actinia swarm: bash docker-swarm.sh See the scripts for hints.