Manual Installation Steps

In most cases, Quick Start is sufficient to set up your local environment. After running the startup-script, your next step is to deploy the Civitas platform locally as explained in the following chapters: DNS Configuration and Customize Inventory.

Caution: If you used the startup.sh script successfully, you can skip this chapter.

In this chapter, we will guide you through the manual installation process for setting up a local Kubernetes cluster, configuring certificates, and installing the key components Nginx Ingress, MetalLB, and Cert-Manager.

1. Create a Root Certificate (optional)

The root certificate is important for enabling secure communication (SSL/TLS) within your Kubernetes cluster.

The repository contains a pre-generated root certificate and a private key that can be used for local deployments in the .ssl directory. To generate a new root certificate, follow the following steps.

You can create a root certificate in one of two ways:

1.1. Using the startup.sh script with the -c Option

This is the automated method for creating a root certificate. The startup.sh script includes a -c option, which automates the process of generating and applying a root certificate.

• When you run: ./startup.sh -c

  • The script will generate a new RSA key and a root certificate.
  • The certificate will be automatically stored in the .ssl directory and applied to your cluster.

1.2. Manual Certificate Creation Using .ssl/create_ca.sh

This is the manual method, which gives you more control over the certificate generation process.

Create a folder to store your certificate files

mkdir .ssl

Generate an RSA key

openssl genrsa -out .ssl/civitas.key 2048

Generate the root certificate

openssl req -x509 -new -nodes -key .ssl/civitas.key -days 3650 -sha256 -out .ssl/civitas.crt \
-subj "/C=DE/ST=State/L=SmartCity/O=KERNBLICK/OU=CivitasCore/CN=$DOMAIN/DN=civitas" \
-addext "subjectAltName=DNS:$DOMAIN,DNS:*.$DOMAIN,IP:127.0.0.1"

Generate the certificate revocation list (CRL)

openssl ca -config ca.conf -gencrl -keyfile .ssl/civitas.key -cert .ssl/civitas.crt -out .ssl/civitas.crl.pem
openssl crl -inform PEM -in .ssl/civitas.crl.pem -outform DER -out .ssl/civitas.crl

Convert the certificate and key files for compatibility (Windows only)

dos2unix .ssl/civitas.crt
dos2unix .ssl/civitas.key

2. Start Kubernetes Cluster

To create a Minikube cluster, use the following command and adjust the parameters as needed.

minikube start --driver=docker --cpus 4 --memory 16384

Alternatively, you can use Docker Desktop or other Kubernetes distributions such as k3s or microk8s for the same process. For example, for k3s use the following command:

k3d cluster create -c local_deployment/k3d-civitas-local.yaml

If you are using a Windows host and want to use the created configuration file from Minikube within Windows Subsystem for Linux (WSL), run the following command to convert the config file to WSL format:

sed -E "s|([A-Za-z]):\\\\|/mnt/\L\1/|g; s|\\\\|/|g" $HOME/.kube/config > $HOME/.kube/config.wsl

3. Get Cluster Info

Retrieve cluster information, including the URL and IP address, to ensure your Kubernetes cluster is running correctly.

kubectl cluster-info --context minikube
minikube ip

For information on the k3s cluster, you would use the following commands:

kubectl cluster-info --context k3d-civitas-local

For the following steps, make sure that Kubectl and Helm are configured to use your cluster context.

kubectl config use-context minikube
        or
kubectl config use-context k3d-civitas-local

4. Install Nginx Ingress

Enable the Nginx Ingress controller to manage external access to your services by setting it up in your cluster with Helm.

helm repo add ingress-nginx https://kubernetes.github.io/ingress-nginx --force-update
helm repo update
helm upgrade --namespace ingress-nginx --install --create-namespace --set allowSnippetAnnotations=true --set controller.publishService.enabled=true ingress-nginx ingress-nginx/ingress-nginx

5. Install and Configure MetalLB

Configure MetalLB for load balancing in your cluster, using a range of IP addresses from your minikube setup to handle external traffic.

export CLUSTER_IP=$(minikube ip)
export IP_RANGE_STOP=$(minikube ip) # You might want to add 20 ip addresses to the range
helm repo add metallb https://metallb.github.io/metallb --force-update
helm repo update
helm upgrade --namespace metallb-system --install --create-namespace metallb metallb/metallb
envsubst < metallb-template.yaml | kubectl apply -f - # wait for metallb to be ready first

6. Install Cert-Manager

Install Cert-Manager using Helm to automate the management and issuance of TLS certificates within your Kubernetes cluster.

helm repo add jetstack https://charts.jetstack.io --force-update
helm repo update
helm upgrade cert-manager jetstack/cert-manager --install --namespace cert-manager --create-namespace --version v1.14.4 --set installCRDs=true

7. Add the CA to the Cluster

Finally, apply your root certificate authority configuration to the cluster to ensure secure communication and certificate validation across your services.

kubectl create configmap --namespace cert-manager civitas.crl.pem --from-file=.ssl/civitas.crl.pem
kubectl create configmap --namespace cert-manager civitas.crl --from-file=.ssl/civitas.crl
kubectl create configmap --namespace cert-manager civitas.crt --from-file=.ssl/civitas.crt
export CA_CERT=$(cat .ssl/civitas.crt | base64 | tr -d '\n')
export CA_KEY=$(cat .ssl/civitas.key | base64 | tr -d '\n')
envsubst < ca-template.yaml | kubectl apply -f -