Prerequisites

Before proceeding with the setup, ensure that you have the following tools installed on your system. These tools will provide the necessary environment for containerization, orchestration, and DNS management throughout the process.

For this setup, a host system and a control system are required.

macOS/Linux

You may use your operating system as both host and control system.

Windows

Windows can be used as host system, but not as control system because Ansible does not support Windows. Thus it is adviced to install Windows Subsystem for Linux (WSL) if you have not already. Now you can use Windows as host system and WSL as control system. Although it generally works, WSL is not officially supported by Ansible. Thus WSL should only be used for development and testing, but not for production.

Host system

1. Docker and Minikube

We use Docker as our Kubernetes driver. Other drivers include Hyperkit, VirtualBox, and Hyper-V.

If you want to use another minikube driver, please refer to the Minikube documentation. If you want to use another Kubernetes distribution, please refer to the respective documentation. Please make sure that the Kubernetes distribution that you are installing does not include Ingress, a cert-manager, and a load balancer, since they will be installed in the next steps specifically for CIVITAS/CORE.

Docker Desktop

macOS:

brew install --cask docker

Windows:

winget install -e --id Docker.DockerDesktop

Check Version (on both macOS and Windows):

docker --version

Minikube

macOS:

brew install minikube

Windows:

winget install -e --id Kubernetes.minikube

Check Version (on both macOS and Windows):

minikube version

2. Kubectl

Kubectl is the command-line tool for interacting with Kubernetes clusters. It allows you to deploy applications, inspect resources, and manage Kubernetes components.

macOS:

brew install kubectl

Windows:

winget install -e --id Kubernetes.kubectl

ℹ️ Docker Desktop is shipped with its own kubectl installation which might override the kubectl version you just installed. So if you have installed Docker Desktop before, you may need to rearrange your PATH variables so that Windows finds this kubectl installation before the kubectl installation of Docker. For more information click here.

Check Version (on both macOS and Windows):

kubectl version --client

3. Helm

Helm is a package manager for Kubernetes, simplifying the process of installing and managing Kubernetes applications by using "Helm charts" (pre-configured Kubernetes resources).

macOS:

brew install helm

Windows:

choco install kubernetes-helm

Check Version (on both macOS and Windows):

helm version

4. OpenSSL

OpenSSL is a toolkit for the implementation of SSL/TLS and cryptographic functions. It's necessary for generating secure certificates and managing encryption during the setup process.

macOS:

brew install openssl

Windows:

choco install openssl

Check Version (on both macOS and Windows):

openssl version

---

5. Acrylic DNS Proxy (Windows) or dnsmasq (Linux/macOS)

DNS management tools like Acrylic DNS Proxy (for Windows) and Dnsmasq (for Linux/macOS) are used for local domain name resolution. They are essential for resolving custom domains like civitas.test in your local Kubernetes environment.

Acrylic DNS Proxy (for Windows):

Download and install Acrylic DNS Proxy from here.

Dnsmasq (for Linux/macOS):

brew install dnsmasq

Once you have installed these tools, verify that they are functioning correctly before proceeding.

Control system

6. Ansible, Ansible Galaxy modules and Python modules

Ansible support for Windows is severly limited. It is necessary to run the following commands in Windows Subsystem for Linux (WSL) instead, as mentioned above.

Also, make sure that all Python and Ansible modules are installed to fulfill the requirements for the control system. You can do that with these commands:

pip install -r requirements.txt
pip install ansible -- ansible-galaxy is included in ansible, but not in ansible.core 
ansible-galaxy collection install -r ansible-collections.yml

The files are available in the repository.

For further information, please refer to the Installation Guide.