Skip to content

Installing Orb control plane

Orb consists of two major components:

  1. The Control Plane—comprised of microservices, communication systems, databases, etc.—deploys to a central location (usually a cloud environment on Kubernetes).
  2. The Orb Agent—a lightweight observability agent—deploys to all the infrastructure you wish to monitor.

Info

The instructions below are for installing the Control Plane. If you just need to install the Orb Agent (orb-agent), see these instructions instead.

The Control Plane can be self-hosted, or you can use our free Orb SaaS service. Self-hosting gives you full privacy and control but is more complex. On the other hand, our SaaS gets you up and running quickly since you only need to create a free account on orb.live and then install the Orb Agent to your infrastructure.

Tip

To run your agent using the self-hosted control plane, disable TLS verification using the enviromental variable below in your provisioning command:

-e ORB_TLS_VERIFY=false

Check an example here.

orb.live

The Orb SaaS platform (orb.live) is now in active development. This free service allows you to enjoy the benefits of the Orb platform without having to run your own control plane.

If you need to install the Orb Agent to be used with orb.live, see these instructions.

Self-host

There are two main deployment methods for those wanting to self-host:

  • Docker Compose - This option is useful for developer or testing installations, allowing you to run both the Orb Control Plane and the Orb Agent on a single machine.
  • Helm Chart - This option is intended for production deployments, requiring access to a Kubernetes cluster.

Follow the instructions below after choosing a self-host option.

Tip

If you're just interested in trying out Orb quickly to see what it's all about, use the Docker Compose method.

Orb with Docker Compose

The Orb repo contains a full Docker Compose environment, useful both for developers wishing to contribute and casual users looking to try Orb for the first time.

Running Orb with Docker Compose requires you to have a copy of the Orb repo, although it is not necessary to build any software as the Compose file will download appropriate versions of the services from Docker Hub.

If you would like to build the software, or if you need to troubleshoot your environment, you can find more detailed instructions on setting up a development environment here.

Requirements

Instructions

git clone https://github.com/orb-community/orb.git

cd orb

make run

This will pull Orb’s containers from Docker Hub and start all services. You may run docker ps to confirm all services started successfully.

If you are running on your local machine, upon success the Orb UI will be available at https://localhost/

Bug

Is the Docker Compose environment not starting correctly? Found a bug? Come talk to us live on Slack in the #orb channel, or file a GitHub issue here.

Orb Helm Chart

Helm is a package manager for Kubernetes. A Helm Chart is a package that allows you to customize your deployment on Kubernetes.

To configure and deploy an Orb Helm Chart, follow the instructions below.

Requirements

Configuration

This guide assumes installation into namespace orb. It requires a HOSTNAME over which you have DNS control. It uses Let's Encrypt for TLS certification management.

  • cd to working directory charts/orb

  • Add helm repos for dependencies.

    helm repo add jaegertracing https://jaegertracing.github.io/helm-charts
helm repo add bitnami https://charts.bitnami.com/bitnami
helm repo add ingress-nginx https://kubernetes.github.io/ingress-nginx
helm repo add jetstack https://charts.jetstack.io
helm repo update
helm dependency update

  • Create orb namespace.

    kubectl create namespace orb

  • Create JWT signing key secret.

    kubectl create secret generic orb-auth-service --from-literal=jwtSecret=MY_SECRET -n orb

  • Create admin user secrets.

    kubectl create secret generic orb-user-service --from-literal=adminEmail=user@example.com --from-literal=adminPassword=12345678 -n orb

  • Deploy ingres-nginx helm (to default namespace) with tcp config map configured from helm for 8883 (MQTTS). Note you need to reference both namespace and helm release name here.

    helm install --set tcp.8883=orb/my-orb-nginx-internal:8883 ingress-nginx ingress-nginx/ingress-nginx

  • Wait for an external IP to be available.

    kubectl --namespace default get services -o wide -w ingress-nginx-controller

  • Choose a HOSTNAME, then point an A record for this hostname to the external IP.

  • Deploy cert manager helm to secure nginx ingress.

    helm install cert-manager jetstack/cert-manager --namespace cert-manager --create-namespace --version v1.5.3 --set installCRDs=true

  • Create Issuer CRDs (in the orb namespace).

    • cp issuers/production-issuer-tpt.yaml issuers/production-issuer.yaml
    • Edit issuers/production-issuer.yaml and change spec.acme.email to a real email address.
    • kubectl create -f issuers/production-issuer.yaml -n orb

  • Install Orb. Replace my-orb with your helm release name.

    helm install --set ingress.hostname=HOSTNAME -n orb my-orb .

Bug

Is the Helm deployment not working correctly? Found a bug? Come talk to us live on Slack in the #orb channel, or file a GitHub issue here.

Upon successful installation, visit our Getting Started section to keep moving forward with Orb.

Orb with Kind

Kind is a tool for running local k8s clusters using docker container as nodes. Follow those steps to setup a local k8s cluster and deploy Orb.

Requirements

Bug

Windows WSL users: WSL is also supported, but for some reason the Orb stack mess up the WSL internal DNS. You can fix that by editing your /etc/wsl.conf and adding the following: 

[network]
generateResolvConf = false
Restart WSL by executing the following on CMD: 
wsl --shutdown
Open WSL terminal again and remove the symbolic link from /etc/resolv.conf: 
sudo unlink /etc/resolv.conf
Create a new /etc/resolv.conf file and add the following: 
nameserver 8.8.8.8
save the file and you are done.

Deploy Orb on Kind

Add kubernetes.docker.internal host as 127.0.0.1 address in your hosts file: 

echo "127.0.0.1 kubernetes.docker.internal" | sudo tee -a /etc/hosts

Clone the Orb Helm charts 

git clone git@github.com:orb-community/orb-helm.git
cd orb-helm

Setup Orb Charts dependencies repositories: 

make prepare-helm

Tip

You just need to run those steps until here once, even if you delete the cluster afterwards.

Use the following command to create the cluster and deploy Orb: 

make kind-create-all

Access the Orb UI by accessing: https://kubernetes.docker.internal/. The following users are created during the mainflux bootstrap:

E-mail Password Role
admin@kind.com pass123456 Admin

Have fun! 🎉 When you are done, you can delete the cluster by running: 

make kind-delete-cluster