Skip to main content
Version: V1-Next

Local Cluster Setup - Linux

This guide covers setting up a local Kubernetes cluster on Linux for CIVITAS/CORE development and testing.

Overview​

Local deployment uses the provided startup.sh script to create a k3d cluster with all necessary components pre-configured. This approach is optimized for development and testing environments.

Prerequisites​

System Requirements​

  • OS: Linux (Ubuntu/Debian recommended)
  • CPU: Minimum 4 cores (8 recommended)
  • RAM: 16GB (if not all components are activated)
  • Storage: 20GB free space
  • Docker: Docker installed and user in docker group

Software Installation​

Install Docker:

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

Install Kubernetes Tools:

# Install k3d
curl -s https://raw.githubusercontent.com/rancher/k3d/main/install.sh | bash

# 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

# Install helm
curl https://raw.githubusercontent.com/helm/helm/main/scripts/get-helm-3 | bash

# Install additional tools
sudo apt-get install -y openssl

Clone Repository:

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

Cluster Setup​

1. Setup Development Environment​

Create Python virtual environment and install dependencies:

python3 -m venv .venv
source .venv/bin/activate
pip install -r requirements.txt
ansible-galaxy collection install -r ansible-collections.yml

2. Create Local Kubernetes Cluster​

Use the startup script to create and configure the cluster:

./local_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

3. Configure Local DNS​

The simplest solution is to add DNS-entries to your hosts-file. Add DNS entries to your hosts file for local development:

Add DNS entries to your hosts file for local development:

sudo sh -c "cat << 'EOF' >> /etc/hosts
127.0.0.1 civitas.test
127.0.0.1 alertmanager.civitas.test
127.0.0.1 api-dashboard.civitas.test
127.0.0.1 api.civitas.test
127.0.0.1 api-admin.civitas.test
127.0.0.1 apim.civitas.test
127.0.0.1 geoportal.civitas.test
127.0.0.1 geoserver.civitas.test
127.0.0.1 grafana.civitas.test
127.0.0.1 idm.civitas.test
127.0.0.1 mimir.civitas.test
127.0.0.1 minio-tenant-console.civitas.test
127.0.0.1 minio-tenant.civitas.test
127.0.0.1 monitoring.civitas.test
127.0.0.1 mqtt.civitas.test
127.0.0.1 oauth.civitas.test
127.0.0.1 oauth.geoportal.civitas.test
127.0.0.1 pgadmin.civitas.test
127.0.0.1 superset.civitas.test
EOF"

4. Trust developer certificate​

It's a good idea to trust the self-signed certificate, which was generated by the startup-script, to avoid issues later on.

  • It depends on your linux distro how you can trust/install the certificate. Please follow your distro-specific guide for this.
  • Certificate location: ./local_deployment/.ssl/civitas.crt

5. Verify Cluster Setup​

Check that all components are running:

# Check cluster 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

Next Steps​

Once your local cluster is ready:

  1. Configure Settings: Use Inventory Configuration Guide with local preset
  2. Install Platform: Follow Platform Installation Guide

Cluster Cleanup​

To remove the local cluster:

# Delete k3d cluster
k3d cluster delete civitas-local

# Remove DNS entries (optional)
sudo sed -i '/civitas\.test/d' /etc/hosts

Troubleshooting​

Common Issues​

Docker Permission Errors

sudo usermod -aG docker $USER
newgrp docker

Port Conflicts

  • Ensure ports 80, 443, 6443 are not in use by other services
  • Use sudo netstat -tulpn | grep :80 to check port usage

Memory Issues

  • Ensure Docker has sufficient memory allocated (8GB minimum)
  • For Docker Desktop: Settings → Resources → Memory

kubectl Context Issues

# List contexts
kubectl config get-contexts

# Switch context
kubectl config use-context k3d-civitas-local