Installation of CIVITAS/CORE

This Platform Installation document will guide through the configuration and rollout of the CIVITAS/CORE platform on a kubernetes cluster.

If you do not have a running kubernetes environment please refer to the Deployment Requirements guide to check what you need for your use case.

Introduction

The platform installation can be done in different approaches. All approaches make use of our curated ansible playbooks to install components and add the platform pre-configuration. These ansible playbooks have to be executed from a controlling system. And the approaches differ by the type of these controlling systems.

• Approach 1: Physical Computer or VM In this case you run the installation based on your personal computer or a provided VM remotely. You only need terminal access: directly local or via ssh. The start of the playbook is triggered manually

• Approach 2: CI/CD controlled on Gitlab In this case the playbook is executed as part of a Gitlab CI/CD Pipeline. With this approach, you can integrate a quality check in your deployments. For instance, testing on development deployments is possible for everyone, production deployments are only possible after merge request confirmations by authorized roles.

This deployment documentation focusses on the first approach. But in general all requirements, tasks and remarks are also valid for the second approach.

Important: For the second approach a working secrets management is needed. This has to be established for your specific environment and cannot be generalized.

Requirements for the control system

The local machine or virtual machine must have the following software installed, to allow the installation of the platform:

• curl
• Any git client
• sshpass
• openssl
• Python >= 3.8
• Helm

The following python modules must be available (e.g., pip install ansible.core). If you use an environment management like conda or similar, make sure these are available in the used environment:

• ansible.core >= 2.13
• openshift 0.12.1
• kubernetes 12.0.1
• ansible-lint >= 5.0
• docker >= 5.0
• jmespath

Finally these ansible modules must be installed, e.g. ansible-galaxy collection install kubernetes.core:

• Ansible Galaxy Module: kubernetes.core >= 2.2
• Ansible Galaxy Module: community.grafana
• Ansible Galaxy Module: community.mongodb:==1.3.2

Installation

After fulfilling all requirements, start with cloning the CIVITAS/CORE Platform repository.

If you want to use the platform as is, the direct clone is sufficient. If you need adjustments, want to configure addons, etc. please make a fork of the platform before and clone this to control system.

Checkout this repository

git clone https://gitlab.com/civitas-connect/civitas-core/civitas-core.git

Before you install the platform, you have to create a so called inventory. An inventory is a file, where the configuration for the ansible playbook is provided. For more details check the ansible documentation.

For the platform we prefer the YAML-notation of the inventories.

We provide a default_inventory.yaml as starting point. Create a copy and adjust this following the Inventory Customization Guide.

The following table defines two scopes for configuring the inventory.

Scope	Description
Sandbox	This inventory is preconfigured to be installed as small as possible. Number of replicas is reduced to a minimum, only one central postgres cluster is installed. Optional components are deactivated, for alternatives only one alternative is installed.
Full Scope	All components are activated and preconfigured. Still one central database is configured. Replicas of important services ensure a first high availability of the platform. (This inventory is a preparation for a production deployment. It has still to be adjusted to your needs. Only use this, when your base cluster is also highly available)

You can store your inventory wherever you want on the control system. A good practice is to keep it out of the current repository structure, to avoid accidentally pushing it to git. The inventory contains secrets, and thus, must not get public!

The default inventory is configured for the full scope. To install the platform in a sandbox mode, you have to adjust the inventory accordingly. For this, you should deactivate grafana,stellio and quantumleap. Additionally you should set all replica numbers in the inventory to 1.

When you are ready with adjusting the inventory for a first try, you can start the installation with the following command.

ansible-playbook -l localhost -i inventory core_platform/playbook.yml

This example assumes you execute the ansible-playbook command in the root directly of the CIVITAS/CORE platform repository. The path to the inventory has to be referenced relative to this path.

Example, with the inventory file on the same folder level as the repository itself:

ansible-playbook -l localhost -i ../inventory.yaml core_platform/playbook.yml

Depending on the installation scope you selected and the performance of your kubernetes cluster the installation will run between 5 and 45 minutes.

There are further possibilities to customize the platform, e.g. changing email templates etc. Please refer to the Further Customization Guide.

Updates

In general, the installation playbooks are designed to be repeatable. So if you want to adjust settings or add additional components, you can change the inventory settings and rerun the playbook command from above.

Restrictions:

• Some values defined in the inventory are not allowed to change after the first installation. These are documented in the Inventory Customization Guide.
• The ansible playbook will not uninstall components to avoid unintended data loss, because of configuration errors. Component deletion and data deletion must be done manually.

Partly execution

It is possible to instruct the playbook to run only portions of the script, if you made changes to the inventory or any deployment(i.e. version update). For each component, or group of components there are tags placed in the playbook file.

For example, to deploy the Postgres operator or Keycloak use the tags defined as follows:

    - name: Setup Postgres Operator
      import_tasks: tasks/operation/postgres_operator.yml
      when: inv_op_stack.postgres_operator.enable
      tags: [ 'ope_postgres' ]
...
    - name: Setup Keycloak Client
	  import_tasks: tasks/access/keycloak.yml
	  when: inv_access.keycloak.enable
      tags: [ 'acc_keycloak' ]

The command for running only the scripts for the Postgres operator and Keycloak client, would look like this:

ansible-playbook -l localhost -i inventory core_platform/playbook.yml --tags operator_postgres,idm_keycloak

It is possible to use a similiar mechanic to omit components, by using the --skip-tags option:

ansible-playbook -l localhost -i inventory core_platform/playbook.yml --skip_tags cm_quantumleap