Skip to main content

Deploy Locally with K3D

The following documentation is a guide for installing OmniSpatial on your local machine using K3D. The guide will walk you through each step of deploying the OmniSpatial dependency components and then the OmniSpatial containers themselves.

note

This guide is intended to install the product on your local machine for testing purposes.

Deployment Prerequisites​

Local Environment Tools

The following tools are required to be installed and available to the person performing the deployment steps.

  • Docker
    • Used by K3D to run the local cluster
  • K3D
    • A lightweight wrapper to run k3s (Rancher Lab’s minimal Kubernetes distribution) in docker
  • Kubernetes CLI (kubectl)
    • Used to interact with the Kubernetes API.
  • Kubernetes Package Manager CLI (HELM)
    • Used to deploy the OmniSpatial HELM charts.
  • A registry YAML file provided by Rizing
    • This file will provide access to Rizing's container registry (will be used later in the deployment steps).

Deployment Overview​

Following this guide will produce a complete OmniSpatial technology stack deployed within Kubernetes. The deployment will result in the following general High-Availability (HA) components:

  • keycloak namespace
  • omni namespace
    • Postgres Database Cluster - used to store OmniSpatial application data
    • OmniSpatial frontend (application) deployment
    • OmniSpatial backend (REST API services) deployment
    • OmniSpatial documentation (User Guide) deployment

Deployment Options​

Option 1) Manual Install​

You can go through the manual steps of deploying the Omni workloads by standing up a K3D cluster and then following the Deploy with Kubernetes steps. K3D is just a lightweight wrapper to run k3s (Rancher Lab’s minimal Kubernetes distribution) in docker.

  1. Make sure you don't have anything running on your host machine that is using port 80 or 443 (such as IIS)
  2. Create a K3D cluster
k3d cluster create -p "80:80@loadbalancer" -p "443:443@loadbalancer" omni-local-cluster
  1. Following the steps outlined in the Deploy with Kubernetes guide
note

K3D will create an ingress class with the name of traefik. Use this class name durint the Create Keycloak Cluster step.

Option 2) Install With Script​

This option will download a script that you can run to create the K3D cluster and deploy the workloads for you.

  1. Download the bootstrap-k3d-cluster.sh script file
    • curl -O https://docs.omni.rizing.app/assets/files/bootstrap-k3d-cluster.sh
  2. Open the file in a text editor (ex: Visual Studio Code)
  3. Set the REGISTRY_USERNAME and REGISTRY_PASSWORD variables to the Rizing registry credential values provided by Rizing
    • If you did not receive these, request them from Rizing support
  4. Update any other desired variables
  5. Open a terminal and navigate to the location of the script
  6. Execute the script
./bootstrap-k3d-cluster.sh
note

You may need to make the file executable on your system.

chmod +x ./bootstrap-k3d-cluster.sh
  1. Confirm that all of the pods in the omni namespace deployed correctly
note

The Omni application will not be able to be fully ran locally as this setup will not have a valid SSL certificate and therefore the Service Worker will not be able to be installed or used (which is a critical component of the Omni application)