Skip to main content
Version: V1-Next

Local Cluster Setup - Windows

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

Overview​

Local deployment on Windows leverages Docker Desktop, WSL2, and optionally VS Code dev containers for a streamlined development experience. The provided startup.sh script creates a k3d cluster with all necessary components pre-configured.

Prerequisites​

System Requirements​

  • OS: Windows 10 version 2004+ or Windows 11
  • CPU: Minimum 4 cores (8 recommended)
  • RAM: Minimum 16GB (required for Windows + Docker + Kubernetes)
  • Storage: 20GB free space
  • WSL2: Windows Subsystem for Linux version 2
  • Docker: Docker Desktop for Windows

Software Installation​

Install Required Software using Winget:

# Run in Administrator PowerShell
winget install -e --id Docker.DockerDesktop
winget install -e --id Microsoft.WSL
winget install -e --id k3d.k3d
winget install -e --id Kubernetes.kubectl
winget install -e --id Helm.Helm
winget install -e --id Git.Git

Alternative Manual Installation:

  1. Docker Desktop for Windows
  2. WSL2
  3. k3d
  4. kubectl
  5. Helm
  6. Git for Windows

Setup WSL2 and Docker​

  1. Enable WSL2:

    # Run in Administrator PowerShell
    wsl --install
    # Restart computer when prompted

  2. Configure Docker Desktop:

    • Start Docker Desktop
    • Go to Settings → General
    • Enable "Use the WSL2 based engine"
    • Go to Settings → Resources → WSL Integration
    • Enable integration with your WSL2 distro
    • Apply settings and restart Docker

Cluster Setup​

Clone Repository:

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

Setup VS Code Dev Container:

  1. Install VS Code
  2. Install the "Dev Containers" extension
  3. Open the cloned folder in VS Code
  4. VS Code will detect the .devcontainer configuration
  5. Click "Reopen in Container" when prompted (or use Ctrl+Shift+P → "Dev Containers: Reopen in Container")

Create Cluster in Dev Container:

# Inside VS Code dev container terminal
./local_deployment/startup.sh -k

Method 2: Using WSL2 Directly​

Setup in WSL2:

# Open WSL2 terminal
wsl

# Install Python dependencies
sudo apt update
sudo apt install python3 python3-pip python3-venv

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

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

Create Cluster:

# In WSL2, inside the repository
./local_deployment/startup.sh -k

Configure Windows DNS​

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

Method 1: Using Notepad as Administrator

  1. Right-click Notepad → "Run as Administrator"
  2. Open file: C:\Windows\System32\drivers\etc\hosts
  3. Add the following lines at the end: 
    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
  4. Save the file

Method 2: Using PowerShell as Administrator

# Run in Administrator PowerShell
$hostsFile = "C:\Windows\System32\drivers\etc\hosts"
$entries = @"

# CIVITAS/CORE Local Development
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
"@

Add-Content -Path $hostsFile -Value $entries

Trust developer certificate​

  • Self-signed certificates will trigger browser warnings
  • Install CA certificate from ./local_deployment/.ssl/civitas.crt to the certificate store "Trusted Root Certification Authorities" of Windows

Verify Cluster Setup​

# Check cluster status (in WSL2 or dev container)
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

Windows-Specific Considerations​

Docker Desktop Configuration​

Ensure Docker Desktop has sufficient resources:

  1. Right-click Docker Desktop tray icon
  2. Go to Settings → Resources → Advanced
  3. Set Memory: 8GB minimum (12GB recommended)
  4. Set CPUs: 4 minimum (6 recommended)
  5. Apply & Restart

WSL2 Configuration​

Configure WSL2 resource limits in C:\Users\<username>\.wslconfig:

[wsl2]
memory=16GB
processors=4
swap=2GB

File System Considerations​

  • Repository Location: Clone in WSL2 filesystem (/home/user/) for better performance
  • Windows Path Access: WSL2 can access Windows files via /mnt/c/
  • Line Endings: Git should handle line endings automatically

Remove DNS Entries:

  1. Open C:\Windows\System32\drivers\etc\hosts as Administrator
  2. Remove lines containing civitas.test
  3. Save the file

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​

Remove k3d Cluster:

# In WSL2 or dev container
k3d cluster delete civitas-local

Troubleshooting​

Common Issues​

WSL2 Not Working

# Check WSL status
wsl --list --verbose

# Restart WSL
wsl --shutdown
wsl

Docker Desktop Issues

  • Restart Docker Desktop
  • Check WSL2 integration in Docker settings
  • Verify Docker is running: docker --version

Port Access Issues

  • Ensure Windows Firewall isn't blocking ports 80, 443
  • Check if Windows services are using ports: 
    netstat -ano | findstr :80

Permission Issues with hosts File

  • Always run Notepad or PowerShell as Administrator
  • Check file permissions on hosts file
  • Temporarily disable antivirus if needed

Dev Container Issues

  • Ensure Docker Desktop is running
  • Restart VS Code
  • Check Docker Desktop WSL2 integration
  • Try: Ctrl+Shift+P → "Dev Containers: Rebuild Container"

kubectl Context Issues

# In WSL2/dev container
kubectl config get-contexts
kubectl config use-context k3d-civitas-local

Windows Performance Tips​

  1. Use WSL2 filesystem for better I/O performance
  2. Allocate sufficient RAM to WSL2 and Docker
  3. Disable Windows Defender realtime scanning for project folder (optional)
  4. Use SSD storage for better performance
  5. Close unnecessary Windows applications to free up memory