Skip to main content
Version: 1.0

Manual Installation Steps

For most cases, Quick Start is sufficient to set up your local environment. After running the script, your next step is to deploy the Civitas platform locally as explained in the following chapters to get the application services up and running in your local Kubernetes cluster.

In this section, we'll 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. Follow these steps to ensure a smooth and specific setup of your environment.

1. Create a Root Certificate (optional)​

The root certificate is important for enabling secure communication (SSL/TLS) within your Kubernetes cluster. There are two ways to create and manage this root certificate:

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.

2. Manual Certificate Creation Using .ssl/create_ca.sh​

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

  • You’ll create the certificate manually using OpenSSL commands to generate a root certificate, an RSA key, and a certificate revocation list (CRL).

  • The manual steps involve:

    1. Create a folder to store your certificate files:

      mkdir .ssl

    2. Generate an RSA key:

      openssl genrsa -out .ssl/civitas.key 2048

    3. 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"

    4. 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

    5. Convert the certificate and key files for compatibility:

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

2. Start Minikube with VirtualBox (Intel-based macOS and Windows only)​

For users on Intel-based macOS or Windows machines, you can launch Minikube with VirtualBox as the driver, allocating sufficient CPU and memory resources to ensure optimal performance of your cluster.

minikube start --driver=virtualbox --cpus 4 --memory 16384 --no-vtx-check

Note: The virtualbox driver is not supported on macOS ARM64 (e.g., Apple M1/M2 chips). For ARM64 users, please use the Docker driver instead:

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

If you are using a Windows host and want to use the created configuration file 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 vital cluster information, including the URL and IP address, to ensure your Kubernetes cluster is running correctly.

kubectl cluster-info --context minikube
minikube ip

4. Install Nginx Ingress​

Enable the Nginx Ingress controller to manage external access to your services by setting it up in Minikube 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 -