Skip to content
adrpinoPublic

About

Your own Vercel

Resources

Stars

0 stars

Watchers

0 watching

Forks

Repository files navigation

Mini-PaaS

A self-hosted Platform-as-a-Service (PaaS) built in Rust. It automates the full lifecycle of web applications using hardware-isolated Firecracker MicroVMs, a rootless ext4 Disk Transmogrifier, Nixpacks zero-config builds, and an asynchronous reverse proxy with transparent scale-to-zero and sub-100ms cold-starts.


Architecture Overview

[ Developer CLI / Web UI ]
            │ (1. Deploy code tarball)
            ▼
   [ Nixpacks Builder ] ──> [ OCI Container Image ]
                                   │
                                   ▼ (2. Rootless Transmogrifier: mkfs.ext4 -d)
                        [ Rootfs Disk: app.ext4 ]
                                   │
                                   ▼ (3. Firecracker REST Daemon / UNIX Socket)
[ Incoming Request ] ──► [ Axum Reverse Proxy ] ──► [ MicroVM (vmlinux Guest Kernel:3000) ]
                                   │
                                   ▼ (4. Idle for >5 mins)
                           [ Reaper Daemon ] (Scale to Zero)

Key Features

  • Multi-Engine Execution (AppRuntime):
    • Firecracker Runtime (src/runtime/firecracker.rs): Military-grade hardware virtualization isolating untrusted tenant code inside dedicated Linux guest kernels via KVM.
    • Local Mock Runtime (src/runtime/mock.rs): Ultra-fast, in-process TCP runtime for sub-50ms local development on macOS without Docker or KVM.
    • Docker Runtime (src/runtime/docker.rs): Containerized execution fallback for standard environments.
  • The Image Transmogrifier (src/transmogrifier.rs): Automatically converts OCI/Docker images into bootable, rootless ext4 MicroVM virtual hard drives using mkfs.ext4 -d.
  • MicroVM Networking (src/runtime/network.rs): Point-to-point /30 subnets (172.19.0.0/16), deterministic MAC generation (06:xx:...), and automated RAII TAP device lifecycle guards.
  • Dynamic Routing & Scale-to-Zero (src/proxy.rs & src/reaper.rs): Subdomain-based proxying with automatic cold-starts on incoming requests and automatic teardown of idle instances.
  • Zero-Config Builds (Nixpacks): Automated language and runtime detection (Node.js, Python, Rust, Go, etc.) without requiring Dockerfiles.
  • Military-Grade Secret Encryption (src/crypto.rs): Environment variables encrypted at rest with ChaCha20-Poly1305 and protected in RAM with zeroizing SecretString.
  • Developer CLI (paas): Terminal client to initialize projects, synchronize .env variables, and deploy code in one command.

Prerequisites

  • Rust: Latest stable toolchain (rustup update).
  • PostgreSQL: Version 14+ (or start instantly with make up).
  • e2fsprogs: Required for rootless mkfs.ext4 disk generation:
    • macOS: brew install e2fsprogs
    • Linux: sudo apt-get install e2fsprogs
  • Docker / Rancher Desktop: Used as a one-time build tool by Nixpacks.
  • Nixpacks: Install via cargo install nixpacks or brew install nixpacks.
  • Lima (Optional for Apple Silicon Macs): brew install lima (for testing real nested KVM microVMs on macOS).

Quickstart & Local Setup

1. Start Database & Run Migrations

# Start local PostgreSQL container in background
make up

# Run the server (migrations and admin user are seeded automatically)
make dev

The server listens on http://0.0.0.0:8080.

2. Environment Configuration

Create a .env file (optional, sensible defaults provided):

DATABASE_URL=postgres://paas_admin:supersecretpassword@localhost:5432/paas_state
PAAS_MASTER_KEY=01234567890123456789012345678901
PAAS_RUNTIME=mock  # Options: mock, docker, firecracker
ADMIN_EMAIL=admin@example.com
ADMIN_PASSWORD=secure-password

Makefile Automation

Standalone commands manage local infrastructure, testing, and formatting:

# Infrastructure Lifecycle
make up            # Start PostgreSQL database container in background
make down          # Stop PostgreSQL container
make db-reset      # Wipe DB volume and re-initialize fresh instance

# Testing & Quality
make test          # Run entire test suite (49+ automated tests)
make test-mock     # Run fast in-process mock runtime tests (<100ms)
make test-disk     # Run rootless ext4 transmogrifier tests
make test-fc       # Run Firecracker lifecycle tests
make test-net      # Run microVM networking and IP allocation tests
make test-proxy    # Run proxy cold-start and reaper lifecycle tests
make lint          # Run cargo fmt check and clippy (-D warnings)
make fmt           # Auto-format all Rust code

# Local Apple Silicon MicroVM Sandbox (Lima)
make vm-provision  # Automatically provision Lima VM with kernel & Firecracker
make vm-up         # Start Lima development VM
make vm-shell      # Open interactive shell inside Lima VM

Developer CLI Workflow (paas)

1. Build and Install the CLI

cargo build --release --bin paas
sudo cp target/release/paas /usr/local/bin/

2. Authenticate

Generate an API key from the Web Dashboard at http://localhost:8080/panel:

paas login

3. Initialize & Deploy an App

Run inside any project directory (e.g. Node.js, Python, Rust):

# Register subdomain
paas init my-app.localhost

# Push encrypted environment variables from local .env
paas env-push

# Build and deploy
paas deploy

Access your application live at http://my-app.localhost:8080!


Project Structure

mini-paas/
├── src/
│   ├── main.rs              # Server entry point and route definitions
│   ├── lib.rs               # Library root exposing core modules
│   ├── proxy.rs             # Reverse proxy, health prober & cold-start routing
│   ├── reaper.rs            # Scale-to-zero background garbage collector
│   ├── transmogrifier.rs    # Rootless OCI-to-ext4 disk generator (mkfs.ext4 -d)
│   ├── crypto.rs            # ChaCha20-Poly1305 encryption & hex encoding
│   ├── db.rs                # PostgreSQL migrations, models & queries
│   ├── state.rs             # Shared AppState with dependency injection
│   ├── api.rs               # Management API for CLI deployments and env sync
│   ├── panel.rs             # Server-side rendered dashboard (Askama + HTMX)
│   ├── build.rs             # Nixpacks image build automation
│   ├── archive.rs           # Secure tar.zst archive extraction (tar-bomb defense)
│   ├── runtime/
│   │   ├── mod.rs           # AppRuntime trait & RuntimeEngine router
│   │   ├── mock.rs          # In-process TCP mock runtime for macOS dev
│   │   ├── firecracker.rs   # Firecracker microVM process & SDK orchestrator
│   │   ├── network.rs       # /30 IP subnet allocator, MAC hashing & TAP guards
│   │   └── docker.rs        # Bollard-based Docker runtime engine
│   └── bin/
│       └── cli.rs           # Developer CLI implementation (`paas`)
├── templates/               # Server-side Askama HTML templates
├── tests/                   # 49+ integration, unit, mock, and lifecycle tests
├── scripts/
│   └── setup_lima.sh        # One-click Lima KVM provisioner for Apple Silicon
├── firecracker_migration.md # Architectural blueprint & migration roadmap
├── Makefile                 # Developer build & test automation
└── AGENTS.md                # AI and human contributor engineering guidelines

Testing & Verification

The project enforces zero-warning compliance across formatting, linting, and tests:

make lint && make test

All 49 unit and integration tests pass in ~4 seconds.

About

Your own Vercel

Resources

Stars

0 stars

Watchers

0 watching

Forks

Releases

Packages

Contributors

Languages