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