mirror of
https://github.com/Dvorinka/Containr.git
synced 2026-06-03 20:12:58 +00:00
Tomas Dvorak
264 lines
7.0 KiB
Markdown
264 lines
7.0 KiB
Markdown
# 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](https://bun.sh/)
|
|
- **Vite**
|
|
- Fast frontend build system
|
|
- [Documentation](https://vitejs.dev/)
|
|
- **React 18**
|
|
- Modern UI framework with hooks and concurrent features
|
|
- [React Documentation](https://react.dev/)
|
|
- **TypeScript (TS / TSX)**
|
|
- Strict typing
|
|
- Shared contracts with backend
|
|
- [Documentation](https://www.typescriptlang.org/)
|
|
- **Tailwind CSS**
|
|
- Utility-first CSS framework
|
|
- Rapid UI development with design tokens
|
|
- [Documentation](https://tailwindcss.com/)
|
|
- **shadcn/ui**
|
|
- Beautiful, accessible component library built on Radix UI
|
|
- [Documentation](https://ui.shadcn.com/)
|
|
- **Lucide React**
|
|
- Beautiful icon library for React
|
|
- [Documentation](https://lucide.dev/)
|
|
|
|
**Documentation:**
|
|
- [React 18](https://react.dev/)
|
|
- [Vite](https://vitejs.dev/)
|
|
- [Tailwind CSS](https://tailwindcss.com/)
|
|
- [shadcn/ui](https://ui.shadcn.com/)
|
|
- [Lucide React](https://lucide.dev/)
|
|
- [React Hook Form](https://react-hook-form.com/)
|
|
- [TanStack Query](https://tanstack.com/query/latest)
|
|
|
|
---
|
|
|
|
### 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.
|