Local Deployment

This guide will show you how to deploy CIVITAS/CORE v2 locally for development and testing purposes.

warning

Warning: This deployment is not intended for production use and should only be used for local development and testing. It may not meet all the requirements for a production deployment and may have different configurations and settings.

Prerequisites

System Requirements

• CPU: Minimum 4 cores (8+ recommended)
• Memory: Minimum 16 GB RAM (24GB+ recommended)
• Disk Space: Minimum 20GB free space (50GB+ recommended)

Install required tools

Install Docker

curl -fsSL https://get.docker.com -o get-docker.sh
sh get-docker.sh
sudo usermod -aG docker $USER
newgrp docker

For more information see the Docker installation guide.

Install kubectl

curl -LO "https://dl.k8s.io/release/$(curl -L -s https://dl.k8s.io/release/stable.txt)/bin/linux/amd64/kubectl"
sudo install -o root -g root -m 0755 kubectl /usr/local/bin/kubectl

For more information see the kubectl installation guide.

Install helm + helm diff plugin

info

You need at least helm v3.18.0. Helm 4 is supported as well.

# for helm v3, use the following command to install helm + helm diff plugin:
curl https://raw.githubusercontent.com/helm/helm/main/scripts/get-helm-3 | bash
helm plugin install https://github.com/databus23/helm-diff

# for helm v4, use the following command to install helm + helm diff plugin:
curl https://raw.githubusercontent.com/helm/helm/main/scripts/get-helm-4 | bash
helm plugin install https://github.com/databus23/helm-diff --verify=false

For more information see the helm installation guide.

Install helmfile

curl -LO https://github.com/helmfile/helmfile/releases/download/v1.2.3/helmfile_1.2.3_linux_amd64.tar.gz
tar -xzf helmfile_1.2.3_linux_amd64.tar.gz && sudo install -o root -g root -m 0755 helmfile /usr/local/bin/helmfile
rm helmfile_1.2.3_linux_amd64.tar.gz

For more information see the helmfile installation guide.

Install linkerd cli

(optional, only if you want to use mTLS in your local deployment)

export LINKERD2_VERSION=edge-25.12.2
curl --proto '=https' --tlsv1.2 -sSfL https://run.linkerd.io/install-edge | sh
export PATH=$HOME/.linkerd2/bin:$PATH
echo 'export PATH="$HOME/.linkerd2/bin:$PATH"' >> ~/.bashrc
linkerd version

For more information see the linkerd installation guide.

Install additional tools

sudo apt-get install -y openssl gettext

Checkout CIVITAS/CORE v2 deployment repository

git clone git@gitlab.com:civitas-connect/civitas-core/civitas-core-v2/civitas-core-deployment.git
cd civitas-core-deployment

Start local kubernetes cluster

./dev_deployment/startup.sh -k

This script will:

• Create a k3d cluster named civitas-local
• Install NGINX Ingress Controller
• Setup MetalLB for LoadBalancer services
• Install and configure cert-manager
• Create self-signed certificates
• Apply cluster configurations

Install linkerd into the cluster

(optional, only if you want to use mTLS in your local deployment)

linkerd check --pre
linkerd install --crds | kubectl apply -f -
linkerd install --set proxy.nativeSidecar=true | kubectl apply -f -
linkerd check

Set up local deployment directory

cp -r defaults/deployment deployment

tip

The deployment directory is in .gitignore of the CIVITAS/CORE v2 deployment repository. Therefore, it can be used as git repository without affecting the main repository. This is very handy for operators to track their own deployments with git.

Configuration

The default local environment should work for the local deployment, but you can adjust it to your needs. See https://docs.core.civitasconnect.digital/docs_v2/Deployment/configuration for more information on how to configure the deployment.

Add hosts to /etc/hosts file

Add the following to your /etc/hosts file:

127.0.0.1 civitas.test
127.0.0.1 portal.civitas.test
127.0.0.1 kafka-ui.civitas.test
127.0.0.1 idm.civitas.test

tip

This list will change over time as more components are added and more subdomains are used.

Start Local Deployment

Create secrets

Before first deployment, you need to create the required secrets in the cluster. For the local deployment, only the Keycloak SMTP secret is required, which is used for sending emails from Keycloak (e.g., for password reset).

kubectl create secret generic keycloak-smtp \
            --from-literal=host='smtp.example.com' \
            --from-literal=port='587' \
            --from-literal=from='noreply@example.com' \
            --from-literal=user='noreply@example.com' \
            --from-literal=password='YOUR_SMTP_PASSWORD' \
            -n dev

Deploy with helmfile

helmfile -f deployment/helmfile.yaml sync -e local
# or (when CRDs are already installed)
helmfile -f deployment/helmfile.yaml apply -e local

First logins

tip

During installation, two users are created in Keycloak:

• the global admin user in the master realm with the username admin. Please do not change or delete this user as it is required for managing the platform realm and all other realms.
• an admin user in the platform realm (defined as instanceSlug) with the username admin@{{domain}} and the same password. This user is created initially and can then be modified, deactivated or deleted as desired. If you delete this user, it will not be created again during the next deployment.

First login Keycloak

After the deployment is complete, you should be able to login to Keycloak with the admin credentials.

You can access the admin password with the following command:

kubectl get secret -n dev keycloak-admin-user -o jsonpath='{.data.password}' | base64 --decode

• URL: http://idm.civitas.test/
• Username: admin
• Password: see above command to get the password

First login to data and user portal

After the deployment is complete, you should be able to login to the data and user portal with the admin credentials.

You can access the admin password with the following command:

kubectl get secret -n dev keycloak-admin-user -o jsonpath='{.data.password}' | base64 --decode

• URL: http://portal.civitas.test/
• Username: admin@civitas.test (replace civitas.test with your configured platform domain if you changed it)
• Password: see above command to get the password

Verify Deployment

Check Cluster Components

Check Status

kubectl cluster-info --context k3d-civitas-local

Verify ingress controller

kubectl get pods -n ingress-nginx

Check cert-manager

kubectl get pods -n cert-manager

Verify MetalLB

kubectl get pods -n metallb-system

Check Deployed Components

kubectl get pods -n dev

Cleanup

To stop the local cluster and clean up resources, run the following command:

k3d cluster delete civitas-local

To remove the civitas.test hosts from your /etc/hosts file, run the following command:

sudo sed -i '/civitas\.test/d' /etc/hosts