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