Skip to main content
Version: V1-Next

Local Cluster Setup - macOS

This guide covers setting up a local Kubernetes cluster on macOS 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: macOS 10.15 (Catalina) or later
  • CPU: Minimum 4 cores (8 recommended)
  • RAM: 16GB (if not all components are activated)
  • Storage: 20GB free space
  • Docker: Docker Desktop for Mac

Software Installation​

Install Docker Desktop:

  1. Download Docker Desktop for Mac from docker.com
  2. Install and start Docker Desktop
  3. Ensure Docker is running (whale icon in menu bar)

Install Kubernetes Tools:

Option 1: Use homebrew​

# Install Homebrew if not already installed
/bin/bash -c "$(curl -fsSL https://raw.githubusercontent.com/Homebrew/install/HEAD/install.sh)"

# Install required tools
brew install k3d kubectl helm

Option 2: Manual installation​

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

# kubectl
curl -LO "https://dl.k8s.io/release/$(curl -L -s https://dl.k8s.io/release/stable.txt)/bin/darwin/amd64/kubectl"
chmod +x ./kubectl
sudo mv ./kubectl /usr/local/bin/kubectl

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

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:

# Create virtual environment
python3 -m venv .venv
source .venv/bin/activate

# Install Python dependencies
pip install -r requirements.txt

# Install Ansible collections
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:

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.

  • Install the CA certificate in Keychain Access
  • Certificate location: ./local_deployment/.ssl/civitas.crt
  • Double-click → Add to Keychain → Trust: Always Trust

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

Docker Desktop Configuration​

Ensure Docker Desktop has sufficient resources:

  1. Open Docker Desktop
  2. Go to Settings → Resources
  3. Set Memory: 16GB minimum (24GB recommended)
  4. Set CPUs: 4 minimum (6 recommended)
  5. Set Disk Image Size: 64GB minimum
  6. Click "Apply & Restart"

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 Desktop Not Running

  • Ensure Docker Desktop is running (whale icon in menu bar)
  • Restart Docker Desktop if needed

Port Conflicts

# Check what's using ports
sudo lsof -i :80
sudo lsof -i :443
sudo lsof -i :6443

Memory/Resource Issues

  • Increase Docker Desktop memory allocation
  • Close other memory-intensive applications
  • Restart Docker Desktop after resource changes

Python/pip Issues

# Upgrade pip
python3 -m pip install --upgrade pip

# Use Python 3 explicitly
python3 -m venv .venv

kubectl Context Issues

# List contexts
kubectl config get-contexts

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

Homebrew Path Issues

# Add Homebrew to PATH (for Apple Silicon Macs)
echo 'export PATH="/opt/homebrew/bin:$PATH"' >> ~/.zshrc
source ~/.zshrc