Skip to main content

​
Deploy Matrix Communication

Deploy Matrix Synapse server, Element.io web client, and Discovery service for real-time chat and video calls. Matrix is deployed via Helm as part of the oriso-platform umbrella chart.
Matrix components are automatically deployed when you run helm install oriso-platform. This guide covers post-deployment configuration and verification.
1

Verify Matrix Deployment

Matrix should already be deployed via Helm. Verify all components are running.
# Check Matrix pods
kubectl get pods -n caritas | grep -E "matrix|element"

# Should see:
# oriso-platform-matrix-synapse-xxx    1/1     Running
# oriso-platform-matrix-discovery-xxx  1/1     Running
# oriso-platform-element-xxx            1/1     Running (if deployed)
All Matrix-related pods should show status Running and 1/1 ready.
If Matrix pods are not running, check the Helm deployment:
helm status oriso-platform -n caritas
kubectl logs -n caritas -l app=matrix-synapse --tail=50
2

Initialize Matrix Database

If this is a fresh deployment, initialize the Matrix PostgreSQL database.
# Check PostgreSQL pod
kubectl get pods -n caritas | grep postgres

# Get Matrix PostgreSQL pod
MATRIX_PG_POD=$(kubectl get pods -n caritas -l app=matrix-postgres -o jsonpath="{.items[0].metadata.name}")

# Import schema (if not already done)
cd ~/online-beratung/caritas-workspace/ORISO-Matrix
kubectl exec -i -n caritas $MATRIX_PG_POD -- \
  psql -U synapse_user synapse < database/matrix-schema-current.sql

# Verify tables
kubectl exec -it -n caritas $MATRIX_PG_POD -- \
  psql -U synapse_user synapse -c "\dt" | head -20
Matrix tables should be created (users, rooms, events, devices, etc.).
3

Verify Matrix Services

Verify Matrix services are operational.
# Check Matrix Synapse API (internal)
kubectl exec -n caritas deployment/oriso-platform-matrix-synapse -- \
  curl -s http://localhost:8008/_matrix/client/versions

# Check Matrix Synapse API (via Ingress)
curl -s https://matrix.oriso-dev.site/_matrix/client/versions

# Check Discovery service
curl -s http://91.99.219.182/.well-known/matrix/server

# Check Element.io (if deployed)
curl -I https://element.oriso-dev.site
  • Matrix Synapse should return JSON with version information
  • Discovery service should return server configuration
  • Element.io should return HTTP 200 OK
4

Configure Matrix Integration

Configure backend and frontend to use Matrix.Backend Configuration (UserService):Matrix integration is configured in UserService. Verify configuration:
# Check UserService environment variables
kubectl get deployment oriso-platform-userservice -n caritas -o yaml | \
  grep -A 5 MATRIX

# Expected:
# - name: MATRIX_SYNAPSE_URL
#   value: http://oriso-platform-matrix-synapse.caritas.svc.cluster.local:8008
# - name: MATRIX_SERVER_NAME
#   value: caritas.local
Frontend Configuration:Frontend Matrix configuration is baked into the Docker image at build time. Verify in .env:
cd ~/online-beratung/caritas-workspace/ORISO-Frontend
cat .env | grep MATRIX

​
Matrix Components

​
Matrix Synapse

  • Service: oriso-platform-matrix-synapse.caritas.svc.cluster.local:8008
  • External: https://matrix.oriso-dev.site
  • Database: PostgreSQL (synapse database)
  • Purpose: Matrix homeserver for chat

​
Matrix Discovery Service

  • Service: oriso-platform-matrix-discovery
  • External: http://91.99.219.182/.well-known/matrix/server
  • Purpose: Federation discovery

​
Element.io (Optional)

  • Service: oriso-platform-element
  • External: https://element.oriso-dev.site or http://91.99.219.182:8087
  • Purpose: Web client for Matrix

​
Integration Details

​
Backend Integration

UserService creates Matrix users and rooms:
  • User registration → Matrix account creation
  • Consultant assignment → Matrix room creation
  • Credentials stored in MariaDB user table

​
Frontend Integration

Frontend uses Matrix JS SDK:
  • Real-time messaging
  • WebRTC calls via LiveKit
  • Event synchronization

​
Troubleshooting

​
Matrix Synapse Not Starting

# Check logs
kubectl logs -n caritas -l app=matrix-synapse --tail=100

# Check database connection
kubectl exec -n caritas deployment/oriso-platform-matrix-synapse -- \
  env | grep DATABASE

# Verify PostgreSQL is accessible
kubectl exec -n caritas deployment/oriso-platform-matrix-synapse -- \
  curl http://oriso-platform-postgresql.caritas.svc.cluster.local:5432

​
Database Connection Issues

# Check PostgreSQL pod
kubectl get pods -n caritas | grep postgres

# Test connection
kubectl exec -it -n caritas deployment/oriso-platform-postgresql -- \
  psql -U synapse_user synapse -c "SELECT 1;"

​
Federation Not Working

# Check discovery service
kubectl logs -n caritas -l app=matrix-discovery

# Test well-known endpoint
curl http://91.99.219.182/.well-known/matrix/server

# Check federation API
curl http://91.99.219.182:8009/_matrix/federation/v1/version

​
Next Steps