RCOM Gateway Installation Guide

Docker Compose

This guide walks you through installing the RCOM Gateway on a Linux server using Docker Compose, with optional support for TLS-secured access. Use this guide for fresh installations or upgrades.

Prerequisites

If you are upgrading from a previous version:

Important

Do not delete Docker volumes. This ensures your existing database data remains intact.

Stop running services

docker compose --profile rabbitmq --profile postgres --profile mosquitto down 

Backup your current installation directory

mv /home/Gateway /home/Gateway_backup_$(date +%F_%T) 

Step 1: Download the Latest RCOM Gateway Package

Use the command below to download and extract the latest version:

wget -O rcom_gateway_compose.zip {{DOWNLOAD_URL}}
unzip rcom_gateway_compose.zip -d /home/Gateway/ 

Step 2: Prepare Runtime Directories

Create necessary directories and apply correct permissions:

cd /home/Gateway/
sudo mkdir -p ./tmp/api/download ./tmp/api/rcom
sudo chown -R 1001:1001 ./tmp/api
sudo chmod -R 775 ./tmp/api

Step 3: Configure Environment Variables

Edit the .env file located in /home/Gateway/ and set the required variables.

Example:

AI2_IMAGE_VERSION_BE=3cb232ad
AI2_IMAGE_VERSION_FE=77d2c4ae 

Optional: Enable TLS (HTTPS for Web Interface)

In .env, set:

TLS_ENABLE=true 

Place your certificate files in /home/Gateway/certificates/:

• nginx.key – Private key
• nginx.pem – Certificate

(Optional) To use custom filenames:

TLS_KEY_FILE_NAME=my_custom.key
TLS_CERT_FILE_NAME=my_custom.pem 

info

TLS is disabled by default. Only enable it if HTTPS is required.

Step 4: Authenticate with Docker Repository

Log in to the private container registry:

docker login www.rcom-repository.de -u 'robot$rcom_gateway+rcom_pull' -p '<Docker Auth Token>' 

Step 5: Pull and Start the Gateway Services

Download container images and start services:

docker compose --profile rabbitmq --profile postgres --profile mosquitto pull
docker compose --profile rabbitmq --profile postgres --profile mosquitto up -d 

info

Your RCOM Gateway instance is now live and running. If TLS is enabled, it will serve the interface securely over HTTPS.

Stopping Services

To safely shut down the gateway:

docker compose --profile rabbitmq --profile postgres --profile mosquitto down 

Final Notes

info

• Docker volumes are preserved by default. No risk to your existing database.

• TLS is fully optional. Ensure certificates are valid and correctly formatted if used.

• You can update the .env file at any time to adjust environment-specific configurations.

Kubernetes

This guide walks you through the installation of the RCOM Gateway on a Linux server using Kubernetes, with optional support for TLS-secured access. Use this guide for fresh installations.

Step 1: Download the Latest RCOM Gateway Package

Use the command below to download and extract the latest version:

wget -O rcom-gateway.zip {{DOWNLOAD_URL}}
unzip rcom-gateway.zip -d /home/rcom-gateway/
cd /home/rcom-gateway/

Step 2: Prepares the System

2.1 Run the Setup Script

Execute the below script. Use the server, username, and password provided on purchase.

bash setup.bash

warning

Only required when preparing a fresh server. Skip if already configured.

2.2 Kubernetes Cluster Requirements

• You need a k3s cluster or a standard Kubernetes cluster (v1.25 or later).
• Ensure kubectl is installed and configured to connect to the cluster:

kubectl version --client
kubectl cluster-info

If you see cluster details and API server connectivity, your setup is correct.

2.3 Configuration File (values.yaml)

All deployment-specific configurations (environment variables, secrets, resources, and scaling policies) are defined in values.yaml.

• Only update the following sections:
  • env → Application environment variables
  • secrets → Sensitive values like API keys or passwords
  • resources → CPU, memory requests, and limits
  • scale → Replica counts

warning

Do not modify other areas of the file unless explicitly required.

Step 3: Configure Environment Variables

Edit the values.yaml file located in /home/rcom-gateway/ and set the required variables.

sudo nano values.yaml

Update the SHA IDs with the latest once.

Example:

RCOM_IMAGE_VERSION_BE=3cb232ad  //use the latest version
RCOM_IMAGE_VERSION_FE=77d2c4ae  //use the latest version

Optional: Enable TLS (HTTPS for Web Interface)

1. In values.yaml, set:

TLS_ENABLE=true

2. Place your certificate files in /home/rcom-gateway/certificates/:

   • nginx.key – Private key
   • nginx.pem – Certificate

3. (Optional) To use custom filenames:

TLS_KEY_FILE_NAME=my_custom.key
TLS_CERT_FILE_NAME=my_custom.pem 

info

TLS is disabled by default. Only enable it if HTTPS is required.

Step 4: Deploying Services

Deployment is managed via Helm. All commands should be executed from the root directory of the codebase.

helm install rcom-gateway . -f values.yaml --set infrastructure.postgres.enabled=true

Managing Deployments

Helm provides commands to maintain and update your deployment.

• Upgrade

  To upgrade, update your values.yaml with the latest SHA ID. If you updated values.yaml or changed chart configurations, apply them with:

  helm upgrade rcom-gateway . -f values.yaml

• View Deployment History

  Track all revisions made to the deployment:

  helm history rcom-gateway

• Rollback

  Revert to a previous revision using:

  helm rollback rcom-gateway <revision_number>
  info

  You can find the <revision_number> from the helm history command output.

• Uninstall (Remove Deployment)

  To completely remove the deployment and all associated Kubernetes objects:

  helm uninstall rcom-gateway

Post-Deployment Validation

After deployment, it’s crucial to validate that all services are running correctly and dependencies are properly bound.

• Pods & Services

  Check the status of pods and services:

  kubectl get pods
  kubectl get svc

  ✅ All pods should be in Running state.

  ✅ Services such as API, UI, DB, MQTT, and RabbitMQ should be exposed.

• Persistent Volumes & Claims

  Verify storage persistence:

  kubectl get pvc
  kubectl get pv

  ✅ Ensure PVCs (Persistent Volume Claims) are bound to PVs (Persistent Volumes).

• Logs & Debugging

  Inspect logs and pod details if issues occur:

  # Logs from a specific pod
  kubectl logs <pod-name>
  
  # Stream logs in real time
  kubectl logs -f <pod-name>
  
  # Pod events and status
  kubectl describe pod <pod-name>

• Cleanup Resources

  If services are removed, leftover PVCs and PVs may still exist. Check:

  kubectl get pods
  kubectl get svc
  kubectl get pvc
  kubectl get pv

  Delete storage if no longer required:

  kubectl delete pvc --all
  kubectl delete pv --all
  warning

  Deleting PVCs/PVs permanently removes stored data. Proceed with caution.

Scaling with HPA (Horizontal Pod Autoscaler)

To handle variable workloads, configure HPA in values.yaml. The HPA dynamically adjusts replica counts based on resource usage.

Key Parameters:

• hpa_max_replicas → Maximum number of pod replicas allowed during scaling.
• hpa_cpu_utilization_percentage → CPU usage threshold that triggers scaling events.
• hpa_memory_utilization_percentage → Memory usage threshold that triggers scaling events.

📈 Behavior:

• Pods scale out when usage exceeds thresholds.
• Pods scale in when usage stabilizes.

This ensures optimal performance and efficient resource consumption.

tip

Best Practices & Final Notes

• Always update env, secrets, resources, and scale in values.yaml before deploying or upgrading.
• Clean up PVCs and PVs only if you no longer need persistent data.
• Monitor deployments regularly using:

kubectl top pods
kubectl top nodes

• Use helm upgrade for applying changes instead of uninstalling and reinstalling, to preserve persistent resources.