Upstand Platform Architecture Guide
In-depth documentation of the Upstand self-hosted PaaS platform.
Welcome to the official production guide for the Upstand PaaS Platform. This documentation details the system design, underlying services, security models, and architectural boundaries of Upstand.
Architectural Overview
Upstand is a modern, container-first self-hosted Platform-as-a-Service (PaaS) designed to orchestrate application builds, compose stacks, and databases across single-node or multi-node Docker Swarm clusters.
1. Control Plane & API Server
The core application server is written in TypeScript using the high-performance Hono framework. It acts as the API control plane, serving:
- Authenticated tRPC router endpoints.
- GitHub, GitLab, and Gitea OAuth Setup/Installation endpoints.
- Background cleanup routines.
- Database operations orchestrated via Drizzle ORM against PostgreSQL.
2. Job Queue & Concurrency Management
Upstand relies on Redis and BullMQ to process application deployments asynchronously.
- Queue Serialization: Each Docker Swarm cluster node has its own isolated build queue (
deployments-queue-<nodeId>). - Build Locking: Redis locks are used to serialize builds per resource, ensuring multiple commits or updates do not compile concurrently.
- Dynamic Concurrency: Deployment workers listen to Redis Pub/Sub events (
upstand:server:concurrency) to adapt their build capacities dynamically based on node hardware settings.
3. UpGal operations assistant
UpGal is an organization-scoped AI agent integrated into the dashboard. It uses typed UI messages, streamed tool states, and explicit approval for mutations. Read the UpGal AI assistant guide for provider configuration, MCP access, security boundaries, and extension guidance.
Feature map
The dashboard supports owner-first authentication, organizations and members, API keys, 2FA, SSO/SCIM, projects and environments, Git provider connections, Docker registries, application builds, database resources, Compose resources, templates, domains and Caddy routes, TLS/ACME, remote servers and SSH keys, Docker Swarm operations, deployment queues, logs and monitoring, scheduled commands, S3 backups, notification channels, cleanup policies, and the UpGal AI assistant. The linked guides in the documentation navigation describe the configuration, permissions, validation, and operational behavior for each area.
Component Workflows
Database Deployments
When a Database resource is deployed:
- Credentials (like passwords) are retrieved and decrypted.
- The database image (PostgreSQL, MySQL, MariaDB, Redis, MongoDB) is pulled from Docker Hub.
- A Docker Swarm service is spawned with local persistent volumes (
upstand-db-data-<id>) bound to/var/lib/...for data durability.
Application Deployments
When a Git repository is deployed:
- The source code repository is cloned to a temporary directory (
.builds/<resourceId>). - Git submodules are recursively resolved if enabled.
- A local container build pipeline builds the Docker image from the root
Dockerfile. - The service is created or updated as a replicated Swarm Service on the
upstand-networkoverlay network. - The temporary directory is wiped.
Security Model & Encryption
Upstand employs a Secret Box cryptography module (aes-256-gcm) to protect credentials stored in PostgreSQL:
- SSH Private Keys: Used for cloning private repositories via SSH, stored fully encrypted.
- S3 Destination Secrets: Encrypted using the cluster-wide master key (
SSH_KEY_ENCRYPTION_KEY_V1) to prevent exposure in case of database leakage. - Encryption Key Rotation: Standardized through key version numbers stored inside payload wrappers.