Getting Started

Open IoT Software platform (OISP) is an open source framework for IoT services that runs on Kubernetes. Start by cloning the repo and checking out the develop branch. This documentation assumes you are running an Ubuntu system (preferably 18.04 LTS), but other Linux distributions should also work with minor modifications.

Note

Most of the functionality described in this documentation is packed into the Makefile in the project root. Run make help for a list of available commands with descriptions.

Running OISP

OISP can be deployed on any Kubernetes cluster that has Helm installed, a volume provisioner and an ingress controller. For development purposes, we recommend a local installation based on k3s, as described in Creating a lightweight local kubernetes cluster.

If you wish to deploy on an external cluster, make sure the following conditions are met:

  1. Your host is configured to manage the cluster, meaning the default kubeconfig file is at ~/.kube/config.
  2. Helm and kubectl are installed on the client and cluster.
  3. The cluster has an Ingress controller and a volume provisioner configured.
  4. The minio operator is installed in the cluster.

Creating a lightweight local kubernetes cluster

Run the following commands from the repository root to create a local k3s cluster on an Ubuntu 18.04 host:

cd kubernetes/util
sh setup-ubuntu-18.04.sh

Note

The script should also run on Ubuntu 16.04 LTS, but you might need to export PATH=$PATH:/snap/bin first. On other Linux distributions, please install the snap packages in the script manually, and run the script afterwards.

The cluster is created in two Docker containers, one for the master and one for the worker. If you like, you can modify the script to make k3s run on bare metal instead of Docker, but the containerized setup is recommended, to avoid issues like port clashes.

If you need to recreate the cluster, simply run make restart-cluster.

Warning

Both scripts are going to replace your ~/.kube/kubeconfig file!

Deployment

If you have access to the OISP dockerhub repository, export your user credentials to your shell:

export DOCKERUSER=[YOURUSERNAME]
read -s DOCKERPASS # type your password and press enter

Otherwise, you will have to build the images yourself. Go to the project root and run make update && make build. You can specify a docker tag for the images being built. Run make help for more details. Afterwards, you have two options to get the images inside the cluster:

  1. Run make import-images, which also takes the DOCKER_TAG and DEBUG parameter, of which the later has to be set to true in order to run tests.
  2. OR push the images to another repo, and adapt the imageCredentials section in kubernetes/values.yaml. You will also need to export your credentials to your shell as described before.

Finally, adapt the kubernetes/values.yaml to fit your needs and run make deploy-oisp.

Note

If you wish to run tests, or have a debugger container inside the cluster with useful tools, run make deploy-oisp-test, which requires you to also build with make build DEBUG=true from the repository root.

Hint

You can watch the deployment process by running watch kubectl -n oisp get pods, or programmatically wait until the system is up and running by using the command make wait-until-ready.

Running end to end tests

If you have deployed with make deploy-oisp-test, you can run make test to make sure everything is working. The tests should take about 3-4 minutes to complete, after the system is up and running.

Using OISP

You need a user account to interact with most of the API functionality. You can create a test user by running make add-test-user. The username is user1@example.com and the password is simply password.

Exposing OISP locally without ingresses

In a production environment, OISP should be exposed using Kubernetes ingresses. However, you might want to skip the configuration for local development purposes. It might also be useful to expose services which are not otherwise publicly accessible. You achieve this using kubefwd.

sudo kubefwd services -n oisp --kubeconfig=/home/[YOUR_USERNAME]/.kube/config

Interacting with OISP

You can interact with OISP using the REST API, or with our SDKs for javascript and python.

Warning

Using the SDKs is the recommended way of interacting with the platform, however, they might not be always up to date with the latest features. Please feel welcome to open issues for any incompatibility problems between the API and the SDKs.

Deploying IoT-Agent with test sensor

The folder ./kubernetes/iot-agent contains an example on how to deploy the oisp-iot-agent with Kubernetes. Once there is a running OISP instance, you can create a test user and deploy the agent by

  1. Run make add-test-user to create a user in OISP.
  2. Create or pull containers oisp-testsensor and oisp-iot-agent.
  3. Import agent images make import-images-agent to import the images to k3s.
  4. Login with the user to the OISP service, create an account and take the activation code from the account main page.
  5. Copy the activation code to ./kubernetes/iot-agent/global-config/activation-code
  6. Update the urls in ./kubernetes/iot-agent/global-config/config.json
  7. Create the global configmap and secrets by (cd ./kubernetes/iot-agent/global-config; sh ./create.sh
  8. Go to the testsensor directory cd ./kubernetes/iot-agent/deploy-testsensor
  9. To create instance n on node node apply the script as follows sh ./create node n
  10. Apply the instance with kubectl apply -f node-n/all.yaml

Cert-Manager

OISP is prepared to be used with cert-manager to retrieve and update certificates from letsencrypt. To configure the cert-manager:

  1. Install cert-manager as described here .
  2. Install issuer kubectl apply -f kubernetes/cert-manager/clusterissuer-prod.yaml. Note that it is managing certificcates cluster wide and thus does not have a namespace.
  3. Adapt email address in kubernetes/certificate_web_prod.yaml. Install the certificate in namespace oisp: kubectl apply -f kubernetes/certificate_web_prod.yaml -n oisp