Installation

This guide installs CIVITAS/CORE V2 on your own Kubernetes cluster.

Try it out gives you a local installation that you delete after the evaluation. This guide gives you a permanent installation that you can share with your team. With the Production Checklist, you can make it ready for production.

Before you start

• Your cluster and your computer agree with the Prerequisites.
• You have configured at least one environment in your deployment/ directory. See Configuration.

In the commands below, replace <env> with the name of your environment and <instanceSlug> with its global.instanceSlug. Run all commands in the root of the deployment repository.

1. Create the SMTP secret

KeycloakKeycloakAn open-source Identity and Access Management (IAM) solution providing SSO and OAuth2/OpenID Connect flows. In CIVITAS/CORE it is used to authenticate users and issue JWTs. sends emails to new users, e.g. to set the password. This includes the initial user. The installation fails if the Secret does not exist. If you do not have an SMTP server yet, use values that are not valid and set the password manually.

Create the keycloak-smtp Secret in the KeycloakKeycloakAn open-source Identity and Access Management (IAM) solution providing SSO and OAuth2/OpenID Connect flows. In CIVITAS/CORE it is used to authenticate users and issue JWTs. namespace <instanceSlug>-keycloak:

kubectl create namespace <instanceSlug>-keycloak
kubectl create -n <instanceSlug>-keycloak secret generic keycloak-smtp \
  --from-literal=host='smtp.yourdomain.example' \
  --from-literal=port='587' \
  --from-literal=from='noreply@yourdomain.example' \
  --from-literal=user='noreply@yourdomain.example' \
  --from-literal=password="${YOUR_SMTP_PASSWORD:?}"

Verify: The command shows the Secret.

kubectl get secret -n <instanceSlug>-keycloak keycloak-smtp

2. Install the operators

The operators manage the databases and message queues of CIVITAS/CORE. All instances in the cluster share the operators, so you install them one time for each cluster. If the operators are already in your cluster, skip this step.

helmfile sync -f deployment/helmfile-operators.yaml -e <env>

The operators go to the namespace in global.operators.namespace (civitas-operators by default).

warning

A change to the operators has an effect on all instances in the cluster. Update the operators before the instances. Do not remove the operators while an instance uses them. The databases and KafkaApache KafkaA distributed event streaming platform. In CIVITAS/CORE it is used as the message bus to transport events, models and data in data flows. continue to run, but nothing manages them: a failed pod does not restart and changes have no effect.

Verify: All pods are Running and the CRDs of CloudNativePGCloudNativePGA Kubernetes operator for running and managing PostgreSQL clusters. In CIVITAS/CORE it is used to provision and operate Postgres databases. and Strimzi exist.

kubectl get pods -n civitas-operators
kubectl get crd | grep -E 'cnpg|strimzi'

3. Install an instance

Install CIVITAS/CORE. This step can take more than 30 minutes.

helmfile sync -f deployment/helmfile-instance.yaml.gotmpl -e <env>

Verify: helmfile stops without an error, and all pods of the instance are Running or Completed.

kubectl get pods -A | grep "^<instanceSlug>-"

Log in

The initial user gets an email with a link to set the password. Open https://portal.<domain> and log in with this user. If you can log in, the installation is complete.

The initial user got no email

Set the password in the KeycloakKeycloakAn open-source Identity and Access Management (IAM) solution providing SSO and OAuth2/OpenID Connect flows. In CIVITAS/CORE it is used to authenticate users and issue JWTs. admin console:

1. Get the password of the KeycloakKeycloakAn open-source Identity and Access Management (IAM) solution providing SSO and OAuth2/OpenID Connect flows. In CIVITAS/CORE it is used to authenticate users and issue JWTs. admin user:

   kubectl get secret -n <instanceSlug>-keycloak keycloak-admin-user \
     -o jsonpath='{.data.password}' | base64 -d

2. Open https://idm.<domain>/admin and log in as admin.
3. Select the realm <instanceSlug> in Manage realms.
4. Open Users and select the initial user.
5. In Credentials, click Set password. Turn off Temporary.
6. In Details, turn on Email verified.

More instances

To install a second instance in the same cluster, e.g. for staging, configure a new environment with a different domain and instanceSlug. Then do step 1 and step 3 with the new environment. The operators are already installed.

4. Apply configuration changes

After you change the configuration of an instance, apply the changes:

helmfile apply -f deployment/helmfile-instance.yaml.gotmpl -e <env>

helmfile apply shows the changes and then upgrades only the releases that changed. helmfile sync also applies changes, but it upgrades all releases. This is slower.

Useful flags for helmfile apply:

• --interactive: ask for confirmation before the upgrade
• --selector component=keycloak: apply one component only

To examine a change without a change to the cluster, use these commands with the same -f and -e flags:

• helmfile diff: show the changes
• helmfile template: render all templates
• helmfile lint: validate the templates

helmfile diff and helmfile apply always show the generated Secrets as changed, also when you did not change them. It is safe to apply these changes: the upgrade keeps the values of existing Secrets.

Verify: All pods of the instance are Running or Completed.

To update to a new CIVITAS/CORE version, see Updating.

Troubleshooting

If a step fails, see Troubleshooting. Start with the events and the pod status in the namespaces of the instance.

Next steps

→ Production Checklist — Steps to do before your installation goes live

→ Updating — Update the operators and the instances to a new version