Skip to main content

​
ORISO Platform - Setup Guide Overview

The Ultimate Step-by-Step Guide for AI Agents & Developers
Version: 1.0.0
Last Updated: October 31, 2025
Platform: ORISO (Online Beratung)
Target: Fresh Ubuntu Server (20.04/22.04)
This guide provides comprehensive instructions for deploying the ORISO Platform on a fresh Ubuntu Server. 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 databases, Redis, RabbitMQ, and Keycloak

​
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
80HTTPOptional, for Let’s Encrypt
443HTTPSOptional
8089Nginx ProxyMain entry point

​
Required Ports (Internal/Services)

PortServiceDescription
3306MariaDBDatabase
27017MongoDBNoSQL database
6379RedisCache and message broker
5672RabbitMQMessage queue
15672RabbitMQ ManagementManagement UI
8080KeycloakAuthentication service
8081TenantServiceTenant management service
8082UserServiceUser management service
8083ConsultingTypeServiceConsulting type service
8084AgencyServiceAgency management service
8085UploadServiceFile upload service
8086VideoServiceVideo service
9001FrontendMain frontend application
9002AdminAdmin panel
8008Matrix SynapseMatrix chat server
8087Element.ioMatrix web client
9021Redis CommanderRedis management UI
9020Redis ExporterRedis metrics exporter
9100Health DashboardSystem health monitoring
3001SignOZOptional observability platform
4317OTEL CollectorOptional OpenTelemetry collector
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