Skip to main content

​
ORISO Platform - Setup Guide Overview

The Ultimate Step-by-Step Guide for AI Agents & Developers
Version: 3.0.0
Last Updated: January 2026
Platform: ORISO (Online Beratung)
Deployment: Kubernetes (k3s) with Helm charts
Status: Production Ready
This guide provides comprehensive instructions for deploying ORISO Platform v3.0.0 on Kubernetes using Helm charts. The platform consists of 21 services deployed via a single umbrella Helm chart. Follow the documentation in order, starting with Initial Server Setup.

Initial Setup

Connect to server, update system, configure hostname and timezone

Network & Firewall

Configure network, UFW firewall, and system limits

Install Software

Install Docker, k3s Kubernetes, kubectl, and additional tools

Clone Repositories

Transfer and clone ORISO repositories to the server

Setup Kubernetes

Verify k3s installation and create namespace

Deploy Infrastructure

Deploy entire platform via Helm umbrella chart (21 services)

​
Server Requirements

​
Hardware Requirements

​
Minimum (Testing/Development)

  • CPU: 4 cores (Intel/AMD x64)
  • RAM: 8GB
  • Disk: 50GB SSD
  • Network: 1 Gbps
  • CPU: 8+ cores (Intel/AMD x64)
  • RAM: 16GB+
  • Disk: 100GB+ SSD (NVMe preferred)
  • Network: 1 Gbps+
  • Backup Storage: External backup solution
For production deployments, we strongly recommend the recommended specifications to ensure optimal performance and reliability.

​
Software Requirements

​
Operating System

  • Primary: Ubuntu Server 22.04 LTS (recommended)
  • Alternative: Ubuntu Server 20.04 LTS
  • Architecture: x86_64 (amd64)
  • Clean Install: Fresh installation (no existing services)

​
Access Requirements

  • SSH Access: Root or sudo user
  • Internet Access: Required for package installation
  • Public IP: Required for external access
  • Domain Name: Optional (for SSL/DNS)

​
Network Requirements

​
Required Ports (External Access)

PortServiceDescription
22SSHSecure shell access
80HTTPIngress Controller (redirects to HTTPS)
443HTTPSIngress Controller (TLS termination)
6443Kubernetes APIOptional, for kubectl access

​
Service Ports (Internal - ClusterIP)

All services are accessible internally via Kubernetes DNS. External access is via Ingress (ports 80/443).
ServicePortInternal URL Pattern
MariaDB3306oriso-platform-mariadb.caritas.svc.cluster.local:3306
MongoDB27017oriso-platform-mongodb.caritas.svc.cluster.local:27017
PostgreSQL5432oriso-platform-postgresql.caritas.svc.cluster.local:5432
Redis6379oriso-platform-redis.caritas.svc.cluster.local:6379
RabbitMQ5672oriso-platform-rabbitmq.caritas.svc.cluster.local:5672
Keycloak8080oriso-platform-keycloak.caritas.svc.cluster.local:8080
TenantService8081oriso-platform-tenantservice.caritas.svc.cluster.local:8081
UserService8082oriso-platform-userservice.caritas.svc.cluster.local:8082
ConsultingTypeService8083oriso-platform-consultingtypeservice.caritas.svc.cluster.local:8083
AgencyService8084oriso-platform-agencyservice.caritas.svc.cluster.local:8084
Matrix Synapse8008oriso-platform-matrix-synapse.caritas.svc.cluster.local:8008
Health Dashboard9001oriso-platform-health-dashboard.caritas.svc.cluster.local:9001
SignOZ3001signoz-frontend.platform.svc.cluster.local:3301
Ensure all required ports are open in your firewall configuration. See Network & Firewall Configuration for details.

​
Quick Start Guide

If you’re ready to begin, start with these essential steps:
  1. Verify Requirements - Ensure your server meets the minimum hardware and software requirements
  2. Connect to Server - SSH into your Ubuntu server with root or sudo access
  3. Follow Setup Guide - Proceed to Initial Server Setup
Once you’ve completed all setup steps, you’ll have a fully functional ORISO platform with:
  • All services running on Kubernetes
  • Databases configured and populated
  • Authentication working (Keycloak)
  • Frontend and Admin accessible
  • Matrix chat operational
  • Monitoring configured

​
Support & Resources

​
ORISO Documentation

  • ORISO-Kubernetes: See ~/caritas-workspace/ORISO-Kubernetes/README.md
  • ORISO-Database: See ~/caritas-workspace/ORISO-Database/README.md
  • ORISO-Keycloak: See ~/caritas-workspace/ORISO-Keycloak/README.md
  • Individual Services: See respective ORISO-*/README.md files

​
Getting Help

If you encounter issues:
  1. Check Troubleshooting Guide
  2. Review Quick Reference
  3. Check service logs: kubectl logs <pod> -n caritas
  4. Check events: kubectl get events -n caritas
  5. Review individual service README files

​
Next Steps