IoTRoutes with Docker images

     IoTRoutes provides public Docker images, along with setup documentation, to simplify platform installation. This solution allows you to quickly set up a complete environment—for testing, demonstration, or even production with minimal functionality.

Docker images are available for the two main components of the platform:

• The IoTRoutes AOS  (Application Object Server)
• The web client

These images are available in the official IoTRoutes public repository on Docker Hub:
👉 https://hub.docker.com/repositories/iotroutes

This chapter describes a concrete example of deploying the IoTRoutes AOS server and web client on a Kubernetes environment, using Nginx as the web server.

Before continuing, it is strongly recommended to consult the previous sections of the documentation describing the general architecture of the platform, in order to fully understand the components to be configured and their interactions

Remember that a minimal installation consists of:

1. Install and configure a MongoDB database instance
2. Install and configure the AOS server provided by IoTRoutes.
3. Install and configure the IoTRoutes web client.

✅ Prerequisites

Before deploying IoTRoutes components via Kubernetes, ensure the following are in place:

• A working Kubernetes cluster (local or remote)
• The NGINX Ingress is installed and operational
• Cert-Manager is configured if you are using TLS with Let's Encrypt

⚠️ Important – Configuring Network Addresses
In the examples in this documentation (and in the provided YAML files), two virtual addresses are used as examples :

• https://my-aos-iotroutes-url.com → for the AOS

• http://iotroutes.local → for the web client

The user must provide IP addresses, internal DNS names, or public domain names that point to the Ingress controller of their Kubernetes cluster.

1. Database server

          IoTRoutes uses NoSQL databases for application configuration and to store IoT messages as well as generated media files or documents. MongoDB is optimized for the application and also recommended for all on-premises installations.  You can check the documentation from the official MongoDB website for installation or cloud usage.   

In production, it is strongly recommended to create separate databases for Data and others for documents, generated reports and media files.

2. Deploying IoTRoutes Server via Kubernetes

The AOS server (IoTRoutes main backend) can be deployed via the public Docker image iotroutes/iotroutes.aos.
This section describes how to configure and launch AOS in a Kubernetes cluster, using three YAML files:

• A ConfigMap containing the application configuration (database connection, security, etc.)
• A Deployment to run the server image
• An Ingress to expose the AOS API in HTTP(S)

The installation exposes a port for the MQTT protocol, as defined in the Deployment.
The administrator can create and manage multiple MQTT brokers from the application user interface; it is therefore necessary to plan the exposure of the corresponding ports according to the brokers activated in your deployment.

🚀 Step 1

📄 File : iotroutes-aos-configmap.yaml

This YAML file defines a Kubernetes ConfigMap that contains the appsettings.json file used to configure the AOS server.

apiVersion: v1
kind: ConfigMap
metadata:
  name: iotroutes-aos-config
data:
  appsettings.json: |
    {
      "Logging": {
        "LogLevel": {
          "Default": "Error",
          "Microsoft": "Warning",
          "Microsoft.Hosting.Lifetime": "Warning"
        }
      },
      "ConnectionStrings": {
        "mongodbDataConnectionString": "mongodb://mongodbUser:Password@dbServer1Name:27017",
        "mongodbDataDbName": "myMainDatabase",
        "mongodbFilesConnectionString": "mongodb://mongodbUser:Password@dbServer2Name:27017",
        "mongodbFilesDbName": "MyFileBucketsDatabase"
      },
      "MQTTEndPointsURL": "",
      "AppServiceName": "iotroutes-aos",
      "Jwt": {
        "Jwt_Secret": "LONG-STRING-FOR-JWT-SECRET-HERE",
        "Jwt_TokenLifetime": "04:00:00",
        "Jwt_RefreshDuration": "04:15:00"
      },
      "Defaults": {
        "DefaultAdmin": {
          "Email": "admiUser@mail.com",
          "Password": "intialPassword"
        },
        "IoTProfiles": "EnvironmentalMonitoring,Lighting,seeMoreOnWebSite..."
      },
      "ApiRateLimit": {
        "Enabled": true,
        "DefaultPerMinute": 60,
        "PerRoute": {
            "/api/auth": 10,
            "/api/definition": 30,
            "/api/FileStore": 30
        }
      },
      "AllowOrigins": "https://my-aos-iotroutes-url.com,http://iotroutes.local"
    }

📝 Description of key parameters

🔐 Security Note: Sensitive values ​​(password and JWT key) must be stored in a Kubernetes Secret in production. Here they are visible for demonstration purposes only. Here the documentation for Kubernetes secrests

🚀 Step 2

📄 File : iotroutes-aos-deploy.yaml

This file contains three Kubernetes objects :

• The deployment that launches the AOS server from the Docker image iotroutes/iotroutes.aos
• A HTT Service (port 80) to expose the platform's REST API
• A MQTT Service (port 1883) for IoT communications with devices.

apiVersion: apps/v1
kind: Deployment
metadata:
  name: iotroutes-aos
spec:
  replicas: 1
  selector:
    matchLabels:
      app: iotroutes-aos
  template:
    metadata:
      labels:
        app: iotroutes-aos
    spec:
      containers:
        - name: iotroutes-aos
          image: iotroutes/iotroutes.aos:latest
          ports:
            - containerPort: 80
            - containerPort: 1883   # for MQTT broker
          env:
            - name: ASPNETCORE_URLS
              value: "http://0.0.0.0:80"
            - name: NODE_IP
              valueFrom:
                fieldRef:
                  fieldPath: status.hostIP
          volumeMounts:
            - name: config-volume
              mountPath: /app/appsettings.json
              subPath: appsettings.json
      volumes:
        - name: config-volume
          configMap:
            name: iotroutes-aos-config
---
apiVersion: v1
kind: Service
metadata:
  name: iotroutes-aos
spec:
  selector:
    app: iotroutes-aos
  ports:
    - port: 80
      targetPort: 80    
  type: ClusterIP
---
apiVersion: v1
kind: Service
metadata:
  name: iotroutes-aos-mqtt
spec:
  selector:
    app: iotroutes-aos
  ports:
    - port: 1883           
      targetPort: 1883 
  type: LoadBalancer

*Note! in some Kubernetes environments, the LoadBalancer service type may not be supported and NodePort or a TCP Ingress must be used (depending on infrastructure).

🚀 Step 3

📄 File : iotroutes-aos-ingress.yaml

This file defines a Kubernetes Ingress resource that exposes the AOS server's HTTP API via a secure public domain name, with TLS via Let's Encrypt, and CORS support enabled to allow calls from the web client.

apiVersion: networking.k8s.io/v1
kind: Ingress
metadata:
  name: iotroutes-aos-ingress
  annotations:
    nginx.ingress.kubernetes.io/rewrite-target: /
    cert-manager.io/cluster-issuer: letsencrypt-cert-manager
    nginx.ingress.kubernetes.io/enable-cors: "true"
    nginx.ingress.kubernetes.io/cors-allow-origin: "*"
    nginx.ingress.kubernetes.io/cors-allow-methods: "*"
spec:
  ingressClassName: nginx
  tls:
    - hosts:
        - my-aos-iotroutes-url.com
      secretName: my-letsencrypt-tls-secret
  rules:
    - host: my-aos-iotroutes-url
      http:
        paths:
          - path: /
            pathType: Prefix
            backend:
              service:
                name: iotroutes-aos
                port:
                  number: 80

After you have finished creating and adapting these files according to your deployment, please apply them using the following commands:

kubectl apply -f iotroutes-aos-configmap.yaml
kubectl apply -f iotroutes-aos-deploy.yaml
kubectl apply -f iotroutes-aos-ingress.yaml

Once applied, these files:

• Exposes the AOS server API at:
  👉 https://my-aos-iotroutes-url.com

• Automatically generates a valid SSL certificate (via Let’s Encrypt)

• Pallows applications (including the IoTRoutes web client) to consume the API via HTTPS

• Allows cross-origin calls with CORS enabled

3. Deploying the IoTRoutes Web Client via Kubernetes

This section explains how to deploy the IoTRoutes web client from the public Docker image iotroutes/iotroutes.web , in a Kubernetes environment.
We will use the following objects:

• ConfigMap : This YAML file defines a Kubernetes ConfigMap used to pass the IoTRoutes web application configuration at deployment time.
• Deployment  :to launch the web client container
• Ingress : to expose the service via NGINX

🚀 Step 1

📄 Create and apply the file : iotroutes-web-configmap.yaml

Allowing you to personalize:

• The title of the application , in th browser(AppTitle)
• The logo displayed (AppLogo)
• The address of the AOS server to which the client should connect (AOSAddresses)

apiVersion: v1
kind: ConfigMap
metadata:
  name: iotroutes-web-config
data:
  appSetting.json: |
    {
      "AppTitle": "My IoTRoutes",
      "AppLogo": "assets/logo.png",
      "AOSAddresses": {
        "default": "https://my-aos-iotroutes-url.com"
      }
    }

Appliquer la configuration:

kubectl apply -f iotroutes-web-deploy.yaml

🚀 Step 2

📄 Create and apply the file : iotroutes-web-deploy.yaml

This deployment creates a Pod based on the image iotroutes/iotroutes.web , by importing the previous configuration.

apiVersion: apps/v1
kind: Deployment
metadata:
  name: iotroutes-web
spec:
  replicas: 1
  selector:
    matchLabels:
      app: iotroutes-web
  template:
    metadata:
      labels:
        app: iotroutes-web
    spec:
      containers:
        - name: iotroutes-web
          image: iotroutes/iotroutes.web:latest
          ports:
            - containerPort: 80
          volumeMounts:
            - name: config-volume
              mountPath: /usr/share/nginx/html/assets/appSetting.json
              subPath: appSetting.json           
      volumes:
        - name: config-volume
          configMap:
            name: iotroutes-web-config
---
apiVersion: v1
kind: Service
metadata:
  name: iotroutes-web
spec:
  selector:
    app: iotroutes-web
  ports:
    - port: 80
      targetPort: 80
  type: ClusterIP

Apply deployment:

kubectl apply -f iotroutes-web-deploy.yaml

🚀 Step 3

📄 Create and apply the file : iotroutes-web-ingress.yaml

This file defines the HTTP access rules, exposing the IoTRoutes web interface via a domain name or IP.

apiVersion: networking.k8s.io/v1
kind: Ingress
metadata:
  name: iotroutes-web-ingress
  annotations:
    nginx.ingress.kubernetes.io/rewrite-target: /
spec:
  ingressClassName: nginx
  tls:
    - hosts:
        - iotroutes.local
  rules:
    - host: iotroutes.local
      http:
        paths:
          - path: /
            pathType: Prefix
            backend:
              service:
                name: iotroutes-web
                port:
                  number: 80

Note: For production deployment, use an SSL certificate here to secure https access

Apply to configure Ingress :

kubectl apply -f iotroutes-web-ingress.yaml

Once all objects are deployed:

• Go to the URL defined in the Ingress file (e.g. http://iotroutes.local/)
• The web interface should open and attempt to connect to the AOS via the URL defined in the ConfigMap

Next : IoTRoutes on-premise Web Client