Wurbr

Wurbr is a self-hostable control plane that brings the seamless developer experience of modern PaaS platforms (such as Vercel or Render) to customer-owned VPS infrastructure (Hetzner, DigitalOcean, AWS EC2, Linode, OVH, or bare metal).

Key Value Pillars: 1. Zero-SSH Operations: Provision, deploy, configure environment variables, manage custom domains, provision SSL certificates, inspect metrics, and stream live logs directly from the web interface. 2. Infrastructure Ownership: All application workloads run directly on the user's servers, while Wurbr operates as the control plane orchestration engine. 3. Dual Deployment Paradigms: Continuous push-to-deploy Automatic Mode and interactive stage-by-stage Guided Mode. 4. Security by Default: Client credentials, private SSH keys, and environment variables are encrypted at rest using AES-256-GCM, with HMAC authentication across webhooks and web terminal sessions.

Wurbr is architected as a modular monolith adhering strictly to Clean Architecture (Hexagonal / Ports & Adapters):

• Inward Dependency Rule: packages/domain contains pure business entities, value objects, and port interfaces with zero external runtime dependencies. packages/application coordinates use cases and depends only on domain contracts. Outer packages (packages/database, packages/ssh, apps/api, apps/worker) implement domain ports. • Web & Database Isolation: apps/web never connects directly to PostgreSQL or remote SSH servers. All state operations route through apps/api or shared client DTOs. • Worker Isolation (ADR-0002): All long-running SSH commands, Git clones, builds, Certbot certificate requests, and system metric harvests are strictly offloaded from HTTP request handlers into background BullMQ workers.

All background workloads are dispatched through BullMQ queues backed by Redis 7:

• Queues & Workers: deployments (builds, pipelines, rollbacks), health (SSH connectivity and host fingerprint validation), metrics (CPU, RAM, Disk utilization harvesting), and domain-ssl (TLS socket handshakes and DNS verification). • Distributed Locking (RedisLockService): Prevents race conditions during concurrent deployments on the same project or server. • Graceful Worker Shutdown: Traps SIGTERM and SIGINT signals, stops accepting new jobs, drains active deployment pipelines cleanly, and closes SSH connection pools safely.

Wurbr provides sub-second visibility into all deployment and server events:

• Scoped Token Issuer (ADR-0007): apps/api generates short-lived, capability-restricted Ably Realtime tokens for authenticated client sessions. • Live Streaming Mesh: apps/worker emits real-time stdout and stderr log lines alongside stage state transitions (deployments:<id>, servers:<id>). • Resilient Fallback: If Ably is unavailable or WebSocket connectivity drops, the frontend automatically falls back to REST polling endpoints (/v1/deployments/:id/logs).

Server management is handled through a high-performance native SSH gateway:

• Ssh2Gateway: Manages SSH key authentication, host fingerprint verification, and remote command streaming. • Interactive Web Terminal (ADR-0009): The web client requests a single-use 60-second HMAC token from POST /v1/servers/:id/terminal-ticket and opens a WebSocket to apps/worker (ws://.../terminal). The worker allocates an SSH pseudo-terminal (PTY) and pipes input/output bidirectionally to in-browser xterm.js. • Metrics Harvester: Executes lightweight non-interactive SSH commands (top -bn1, free -m, df -k, cat /proc/loadavg) and appends samples to PostgreSQL, with automated 7-day retention pruning and SVG sparkline visualizations.

Wurbr provides automated domain configuration and TLS lifecycle management:

• Target DNS Guidance: Computes the target server IP and outputs exact A and CNAME record configuration instructions for custom domains. • Automated Certbot Provisioning: Remotely issues and renews Let's Encrypt SSL certificates over SSH with automated Nginx/Caddy renewal hooks. • Continuous TLS Verification: Background workers periodically probe SSL expiration dates and update domain status badges (ACTIVE, EXPIRING, EXPIRED).

Security is engineered into every layer of the platform:

• Envelope Encryption at Rest (AES-256-GCM, ADR-0005): SSH private keys, passphrases, and environment variables are encrypted with 256-bit keys and stored as wurbr1.<iv>.<tag>.<ciphertext>. • Session Revocation & JWT Versioning (ADR-0014): Incrementing sessionVersion on user models instantly invalidates all other active JWT sessions upon password reset. • GitHub Webhook HMAC Verification: Validates x-hub-signature-256 signatures with Redis delivery ID tracking to prevent replay attacks. • Immutable Audit Trail: Every critical mutation generates an immutable AuditLog record capturing actor, action, resource, and scrubbed metadata.

The database layer uses PostgreSQL with Prisma ORM structuring multi-tenant entities:

• Tenancy & Membership: User, Organization, and OrganizationMember with granular RBAC roles (OWNER, MEMBER, VIEWER). • Workloads & Infrastructure: Project, Server (with credentialsEncrypted), Deployment, DeploymentStage, DeploymentStep, DeploymentLogLine, and ServerMetricSample.

Shipped an enterprise-grade, open-source self-hostable PaaS control plane delivering modern cloud developer ergonomics directly to customer-owned VPS infrastructure.