Skip to main content

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 apicurio.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

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

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