Portal (Budibase)

User-facing portal at https://portal.ravenhelm.dev powered by Budibase.

Overview

The portal provides a self-service interface for users to:

View and edit profile settings
Manage contacts
Upload and organize documents (with RAG indexing)
Track support cases/tickets
View Norns conversation history
Monitor n8n automation executions

Quick Start

Builder Access

https://portal.ravenhelm.dev/builder/app/app_dev_e454eb8b55794349a85d52d613015717

Email: admin@ravenhelm.dev
Password: See BB_ADMIN_USER_PASSWORD in budibase/.env

Published App

https://portal.ravenhelm.dev/portal

Architecture

                    Traefik (TLS)
                         │
    portal.ravenhelm.dev │
         │               │
    ┌────┴────┐    ┌─────┴─────┐   ┌─────────────┐
    │Budibase │    │ PostgreSQL│   │ Zitadel SSO │
    │ Stack   │◄───┤ ravenmaskos│   │             │
    └────┬────┘    └───────────┘   └─────────────┘
         │
    ┌────┴────────────────────────────┐
    │         REST Datasources        │
    ├────────────────┬────────────────┤
    │  Norns Agent   │      n8n       │
    │  :8000         │     :5678      │
    └────────────────┴────────────────┘

Components

Container	Image	Purpose
budibase-proxy	budibase/proxy	Nginx reverse proxy (port 10000)
budibase-app	budibase/apps	Main application (port 4002)
budibase-worker	budibase/worker	Background tasks (port 4003)
budibase-couchdb	budibase/couchdb	Internal app storage
budibase-minio	minio/minio	File storage
budibase-redis	redis:7-alpine	Cache

Configured Resources

App

Property	Value
App ID	`app_dev_e454eb8b55794349a85d52d613015717`
Name	Portal
URL	/portal
Status	Development

Datasources

PostgreSQL: RavenmaskOS Database

Property	Value
ID	`datasource_08f6af53d04c422282dec573526f82ae`
Host	postgres
Database	ravenmaskos
User	ravenhelm

Imported Tables:

users - User profiles
contacts - Contact lists
documents - Document metadata
portal_cases - Support tickets
portal_case_comments - Ticket comments
v_portal_cases_full - Cases with user/assignee names (view)

REST: Norns Agent API

Property	Value
ID	`datasource_9c51590a82f64102a5fd6460bcb1b0ab`
URL	http://docs/AI-ML-Platform/norns-agent:8000
Auth	X-API-Key header

Queries:

List Sessions - GET /sessions?user_id={{userId}}&limit=50
Get Session Detail - GET /sessions/{{sessionId}}

REST: n8n Automations

Property	Value
ID	`datasource_a7dec592678d4e5abc540153d8cea3a2`
URL	http://n8n:5678
Auth	x-n8n-api-key header

Queries:

List Executions - GET /api/v1/executions?limit=50

Generate Screens

Budibase's screen API requires workspace configuration not available in self-hosted. Create screens via the Builder UI:

1. Open Builder

Navigate to: https://portal.ravenhelm.dev/builder/app/app_dev_e454eb8b55794349a85d52d613015717

2. Auto-Generate Table Screens

For each table, click Design → Add Screen → Autogenerated screens:

Table	Screen Name	Route
contacts	Contacts	/contacts
documents	Documents	/documents
portal_cases	Cases	/cases
users	Profile	/profile

3. Add Query-Based Screens

Click Design → Add Screen → Blank screen:

Norns History (/history)

Add Data Provider component
Set Data source: Query → Norns Agent API → List Sessions
Add Table component inside provider
Configure columns: channel, created_at, message_count, summary

Automations (/automations)

Add Data Provider component
Set Data source: Query → n8n Automations → List Executions
Add Table component inside provider
Configure columns: workflowName, status, startedAt, stoppedAt

Click Navigation in left panel:

Add links for all screens
Set home screen to /contacts or /

5. Publish

Click Publish button in top right to deploy.

Authentication

SSO via Zitadel OIDC

Property	Value
OIDC App	Portal (Budibase) in Zitadel
Client ID	See 1Password "Portal OIDC - Zitadel"
Redirect URI	https://portal.ravenhelm.dev/api/global/auth/oidc/callback
Config URL	https://auth.ravenhelm.dev/.well-known/openid-configuration

Configure in Budibase: Settings → Auth → OpenID Connect

Screen Designs

Profile Screen

Read-only (from Zitadel): email, display_name, roles
Editable (local): timezone, phone, notification_preferences

Contacts Screen

CRUD table with columns: name, email, phone, company, tags, favorite
Filter by search, tags, favorites

Documents Screen

Upload with drag-drop
Columns: filename, category, tags, rag_status, uploaded_at
RAG status indicators: ⏳ pending, 🔄 processing, ✅ indexed, ❌ failed

Cases Screen

List with status badges (open, in_progress, waiting, resolved, closed)
Priority indicators (P1-P4)
Detail view with comments thread

Norns History Screen

Session list with channel icons (💬 Slack, 📞 Voice, 🌐 Web, 🗣️ Siri)
Click to view full conversation transcript

Automations Screen

Workflow execution list
Status: ✅ success, ❌ failed, 🔄 running
Link to n8n execution detail

Management

Service Location

/Users/ravenhelm/ravenhelm/services/budibase/
├── docker-compose.yml
├── .env                    # Service-specific secrets
└── generate-screens.md     # Screen generation guide

Data Location

/Users/ravenhelm/ravenhelm/data/budibase/
├── couchdb/               # CouchDB data (apps, configs)
├── minio/                 # MinIO object storage (uploads)
└── redis/                 # Redis persistence

Commands

# Start/Stop
cd /Users/ravenhelm/ravenhelm/services/budibase
docker compose up -d
docker compose down
docker compose logs -f

# Check status
docker ps --filter 'name=budibase'

# View specific logs
docker logs -f budibase-app
docker logs -f budibase-proxy

Troubleshooting

Portal Not Loading

Check containers: docker ps --filter 'name=budibase'
Check proxy logs: docker logs budibase-proxy
Verify Traefik routing: docker logs traefik 2>&1 | grep budibase

Verify redirect URI matches exactly in Zitadel
Check worker logs: docker logs budibase-worker --tail 50
Ensure https:// scheme

Database Connection Failed

# Test from inside container
docker exec budibase-app ping -c 2 postgres

REST API Errors

# Test Norns
curl -s -H "X-API-Key: <key>" http://localhost:8000/api/health

# Test n8n (from odin)
curl -s -H "x-n8n-api-key: <key>" http://n8n:5678/api/v1/workflows

Secrets Reference

Secret	Location	Purpose
BB_ADMIN_USER_PASSWORD	budibase/.env	Admin login
BB_COUCH_DB_PASSWORD	budibase/.env	CouchDB auth
BB_MINIO_SECRET_KEY	budibase/.env	MinIO auth
BB_JWT_SECRET	budibase/.env	Session tokens
POSTGRES_PASSWORD	secrets/.env	Database auth
NORNS_API_KEY	secrets/.env	Norns API
n8n API Key	1Password	n8n API
OIDC Client Secret	1Password	Zitadel SSO

Identity-Management - Zitadel SSO configuration
AI-ML-Platform - Norns agent and RAG system
Automation - n8n workflows
Infrastructure - PostgreSQL, Traefik

Overview​

Quick Start​

Builder Access​

Published App​

Architecture​

Components​

Configured Resources​

App​

Datasources​

PostgreSQL: RavenmaskOS Database​

REST: Norns Agent API​

REST: n8n Automations​

Generate Screens​

1. Open Builder​

2. Auto-Generate Table Screens​

3. Add Query-Based Screens​

Norns History (/history)​

Automations (/automations)​

4. Configure Navigation​

5. Publish​

Authentication​

SSO via Zitadel OIDC​

Screen Designs​

Profile Screen​

Contacts Screen​

Documents Screen​

Cases Screen​

Norns History Screen​

Automations Screen​

Management​

Service Location​

Data Location​

Commands​

Troubleshooting​

Portal Not Loading​

OIDC Login Fails​

Database Connection Failed​

REST API Errors​

Secrets Reference​

Related Pages​