Try CIVITAS/CORE locally

This guide installs CIVITAS/CORE V2 on a local k3d cluster on your computer. At the end, you can log in to the portal and try the platform.

Not for production

This installation is for evaluation only. It uses a local certificate authority, sends no emails and has no service mesh and no runtime policies. Multi-factor authentication is disabled. Do not keep data in it. For a real installation, follow the Prerequisites and the Installation.

What you do

1. Create a local Kubernetes cluster with k3d.
2. Prepare the cluster: certificates and DNS.
3. Install the CIVITAS/CORE operators, then the CIVITAS/CORE platform.
4. Set a password for the initial user and log in.

The installation takes approximately 45 minutes.

info

If you already have a Kubernetes cluster, you can skip the k3d steps. Make sure that your cluster has the required cluster components and change deployment/environments/try-it-out/global.yaml.gotmpl to agree with your cluster.

Requirements

• A Linux or macOS computer with x86_64 architecture, 9 CPU cores and 16 GiB of free RAM
• Docker
• k3d version 5
• mkcert
• The tools for the installation: kubectl, Helm, the Helm Diff plugin, helmfile and git

Create the cluster

Create a cluster with the name civitas. The ports 80 and 443 of your computer go to the ingress controller in the cluster. k3d also sets your kubectl context to the new cluster.

k3d cluster create civitas -p "80:80@loadbalancer" -p "443:443@loadbalancer"

Prepare the cluster

Certificates

CIVITAS/CORE uses cert-manager to issue TLS certificates. In this guide, cert-manager uses a local certificate authority (CA) from mkcert. Your browser trusts this CA, so you get no certificate warnings.

Create the local CA and add it to the trust stores of your computer:

mkcert -install

Install cert-manager:

helm install cert-manager oci://quay.io/jetstack/charts/cert-manager \
  --version v1.21.2 \
  --namespace cert-manager --create-namespace \
  --set crds.enabled=true \
  --wait

Give the CA to cert-manager. The name of the ClusterIssuer must be selfsigned-ca, because CIVITAS/CORE uses this name to find the CA.

kubectl -n cert-manager create secret tls ca-secret \
  --cert="$(mkcert -CAROOT)/rootCA.pem" \
  --key="$(mkcert -CAROOT)/rootCA-key.pem"

kubectl apply -f - <<EOF
apiVersion: cert-manager.io/v1
kind: ClusterIssuer
metadata:
  name: selfsigned-ca
spec:
  ca:
    secretName: ca-secret
EOF

DNS

CIVITAS/CORE uses the domain civitas.test. Your browser and the components in the cluster must find the CIVITAS/CORE host names.

Add the host names to /etc/hosts on your computer:

echo "127.0.0.1 idm.civitas.test portal.civitas.test management.civitas.test api.civitas.test dashboard.civitas.test" \
  | sudo tee -a /etc/hosts

In the cluster, send all civitas.test names to the ingress controller. Then restart CoreDNS to load the change.

kubectl apply -f - <<'EOF'
apiVersion: v1
kind: ConfigMap
metadata:
  name: coredns-custom
  namespace: kube-system
data:
  civitas.server: |
    civitas.test {
      template IN ANY {
        match "^(.*\\.)?civitas\\.test\\.$"
        answer "{{ .Name }} 60 IN CNAME traefik.kube-system.svc.cluster.local."
        fallthrough
      }
    }
EOF
kubectl -n kube-system rollout restart deployment coredns

Install CIVITAS/CORE

Get the deployment repository and use the try-it-out environment. This environment is ready to use. You do not have to change it.

git clone https://gitlab.com/civitas-connect/civitas-core/civitas-core-v2/civitas-core-deployment.git
cd civitas-core-deployment
cp -r defaults/deployment deployment

CIVITAS/CORE installs in two parts:

• The operators manage databases and message queues for CIVITAS/CORE. You install them one time for each cluster.
• The platform is CIVITAS/CORE itself.

We recommend this procedure also for production. See Installation.

Install the operators:

helmfile sync -f deployment/helmfile-operators.yaml -e try-it-out

Install the platform. This step takes approximately 40 minutes.

helmfile sync -f deployment/helmfile-instance.yaml.gotmpl -e try-it-out

Make sure that all pods are Running or Completed:

kubectl get pods -A

If a step fails, see Troubleshooting.

Set your password

The installation creates the initial user admin@civitas.test with administrator rights. This user has no password. Usually, CIVITAS/CORE sends an email to set the password, but this installation sends no emails.

Set a password with the script below. The script also removes the email verification and the two-factor setup for this user. It writes the user name and a generated password to admin.env.

NAMESPACE=civitas-keycloak KEYCLOAK_REALM=civitas AUTH_DOTENV_FILE=./admin.env \
  scripts/ci/set-initial-user-password.sh
grep ^AUTH_ admin.env

Log in

Open https://portal.civitas.test in your browser. Log in with the user name AUTH_USER and the password AUTH_PASSWORD from admin.env.

You now see the CIVITAS/CORE portal.

Next steps

→ Getting Started — Learn the core concepts of CIVITAS/CORE

→ Quick start — Connect external data and publish it as a DatasetDatasetA data-related element that contains processed data and makes it available for consumption. A Dataset is populated via Pipelines and carries Metadata and access permissions.

→ Onboard Users — Add more users and give them Roles

→ Configuration — Change your deployment, e.g. the components and their settings

→ Prerequisites — Prepare a real installation

Remove the installation

Delete the cluster and all its data:

k3d cluster delete civitas

Remove the mkcert CA from the trust stores of your computer:

mkcert -uninstall

Also remove the civitas.test line from /etc/hosts.