Containr/docs/archive/research/project.md

Self-Hosted PaaS on Proxmox (Railway-like Platform)

A fully self-hosted, open-source Platform-as-a-Service designed to run on top of Proxmox infrastructure, providing a Railway-like developer experience: Git-based deployments, container orchestration, automatic scaling, load balancing, and observability — all under your control.

---

🎯 Goals

• Railway-like UX, fully self-hosted
• Built primarily on Proxmox + Docker
• Horizontal scaling across multiple VMs/LXCs
• Agent-based orchestration (no Kubernetes required)
• Git-driven deploys
• Production-grade networking, metrics, and reliability

---

🧱 Core Architecture

• Control Plane: Central API + scheduler
• Node Agents: Lightweight daemons running on each VM/LXC
• Execution Layer: Docker containers
• Networking: Traefik reverse proxy & load balancer
• State Layer: Externalized databases and caches

---

🧠 Technology Stack

Backend / Control Plane

• Go (primary language)
  • Scheduler
  • Orchestration logic
  • API server
  • Scaling engine
• Python (auxiliary tooling)
  • Metrics processing
  • Background jobs
  • Scripts where Go is impractical
• Rust (performance-critical components)
  • Node agent (optional)
  • Low-level system monitoring
  • High-throughput data collectors

---

Frontend / Dashboard

• Bun
  • Package manager
  • Runtime for tooling & scripts
  • Documentation
• Vite
  • Fast frontend build system
  • Documentation
• React 18
  • Modern UI framework with hooks and concurrent features
  • React Documentation
• TypeScript (TS / TSX)
  • Strict typing
  • Shared contracts with backend
  • Documentation
• Tailwind CSS
  • Utility-first CSS framework
  • Rapid UI development with design tokens
  • Documentation
• shadcn/ui
  • Beautiful, accessible component library built on Radix UI
  • Documentation
• Lucide React
  • Beautiful icon library for React
  • Documentation

Documentation:

• React 18
• Vite
• Tailwind CSS
• shadcn/ui
• Lucide React
• React Hook Form
• TanStack Query

---

Infrastructure & Runtime

• Docker
  • Container runtime
  • Image builds & execution
• Docker Compose / Custom Orchestrator
  • Service definitions
  • Replica management
• Traefik
  • Reverse proxy
  • Automatic service discovery
  • TLS & routing
• Proxmox
  • VM & LXC orchestration
  • Compute isolation
  • Infrastructure backbone

---

Data & State

• PostgreSQL
  • Persistent platform state
  • Users, apps, deployments, scaling rules
• Redis
  • Caching
  • Session storage
  • Queues & pub/sub

---

🏗️ Build System & Deployment

Builder Types (Railway-inspired)

1️⃣ Nixpacks (Primary, Default Builder) ⭐

Auto-detection build system based on Nix for reproducible builds.

• How it works: Scans repo for go.mod, package.json, requirements.txt, etc.
• Supports: Go, Node.js, Bun, Python, Ruby, PHP, Rust, Deno, Static sites
• Advantages: No Dockerfile needed, fast builds, reproducible, easy overrides
• Default choice: Used when no other builder is specified

2️⃣ Dockerfile Builder

Standard Docker build using your existing Dockerfile.

• When to use: Complex builds, custom system dependencies, non-standard runtimes
• Control: Full control over base image, OS packages, multi-stage builds
• Tradeoff: Slower than Nixpacks, more responsibility

3️⃣ Prebuilt Image Deployment

Deploy existing container images from Docker Hub, GHCR, or any OCI registry.

• Use cases: Workers, infrastructure tools, third-party services, optimized custom images
• Process: No build step - Railway pulls and runs the image directly

4️⃣ Platform Templates

Predefined service configurations that wrap around the above builders.

• Function: Predefine services, choose builder type (usually Nixpacks), preconfigure variables & databases
• Underlying: Still uses Nixpacks, Dockerfile, or prebuilt images

Builder Selection Logic

Dockerfile present? → Docker builder
Else if image specified? → Image deploy  
Else → Nixpacks (default)

Build Output

Regardless of builder type, the result is always:

• Container image
• Versioned per deployment
• Immutable
• Rollback-able

Stack Mapping

• Go backend → Nixpacks (perfect fit)
• Vite/React/Bun → Nixpacks
• Rust helpers → Nixpacks or Dockerfile
• Custom system deps → Dockerfile
• Workers/cron → Prebuilt image or Nixpacks

---

🔁 Scaling Model

• Horizontal scaling via container replicas
• Node-aware scheduling across Proxmox VMs/LXCs
• Metrics-based auto-scaling:
  • CPU
  • Memory
  • Request rate
• Stateless application containers
• Externalized state (DB, cache, storage)

---

📦 Deployment Flow

1. Git push / webhook trigger
2. Backend schedules build
3. Docker image is built & stored
4. Scheduler selects optimal nodes
5. Node agents start containers
6. Traefik automatically routes traffic
7. Metrics collected → scaling decisions applied

---

� Analytics & Monitoring

Umami Integration

• Privacy-focused web analytics for user insights
• Self-hosted analytics dashboard for application monitoring
• Real-time visitor tracking with geographic and device data
• Performance metrics including bounce rates and session duration
• Traffic source analysis and top page tracking
• GDPR compliant with no personal data collection
• Integration points:
  • Dashboard analytics overview
  • Project-specific metrics
  • Service performance tracking
  • User behavior analysis

Built-in Monitoring

• Real-time metrics with custom visualizations
• Service health monitoring with status indicators
• Resource usage tracking (CPU, memory, storage, network)
• Geographic service distribution with interactive globe
• Performance graphs and data visualizations
• Build logs integration with step-by-step progress tracking
• Deployment history with rollback capabilities

---

�🔐 Networking & Security

• TLS termination via Traefik
• Internal service networking
• Agent authentication via tokens / mTLS
• No direct Docker socket exposure to UI

---

🧩 Design Principles

• Infrastructure-first (Proxmox as the cloud)
• Stateless by default
• Explicit over magical
• Horizontal scalability
• Fail-fast & observable
• Open-source friendly

---

🚀 Long-Term Vision

• Multi-cluster support
• Cloud bursting (home → cloud nodes)
• Preview environments per Git branch
• Resource-based billing (optional)
• Plugin system for runtimes & buildpacks

---

📄 License

MIT / Apache-2.0 (TBD)

---

🛠️ Status

Early architecture & design phase.