prole/README.md

# ###########################
# ╭──────────────────────╮ #
# │               _      │ #
# │  _ __ _ _ ___| |___  │ #
# │ | '_ \ '_/ _ \ / -_) │ #
# │ | .__/_| \___/_\___| │ #
# │ |_|                  │ #
# ╰──────────────────────╯ #
# ###########################

Prole

Prole makes it practical to run a Supabase-style platform in an air-gapped environment.

It packages the core building blocks needed for a modern internal developer platform around PostgreSQL, object storage, secrets, auth, observability, and Kubernetes-native operations — with a bias toward simple deployment, shard-based scale-out, and deterministic ingestion.

---

Platform badges

---

What Prole is

Prole is an infrastructure stack for running a Supabase-like data and application platform in constrained environments, including:

• air-gapped networks
• edge and small-cluster deployments
• sovereign or private data environments
• disconnected labs and field systems
• internal platforms where cloud dependencies are undesirable

The design goal is not to mimic Supabase branding or every managed feature exactly.

The design goal is to provide the useful substrate people actually want:

• PostgreSQL as the center of gravity
• object storage
• auth integration
• secret management
• ingress and service exposure
• observability
• reproducible Kubernetes deployment
• application and worker services around the database
• ingestion patterns that are safe, resumable, and idempotent

---

Core idea

Prole can run Supabase-style workloads in an air gap.

That means:

• PostgreSQL remains the system of record
• services are deployed on Kubernetes
• auth can come from local identity systems or cloud OIDC where available
• object storage stays inside the environment
• secrets stay inside the environment
• ingestion does not depend on live internet services
• the stack can be deployed in shards for locality, resilience, and operational simplicity

---

Main components

Application layer

• Next.js app for the user-facing platform
• prole-agent worker for async and background execution

Data layer

• CloudNativePG for PostgreSQL lifecycle on Kubernetes
• PostgreSQL as the primary relational store
• append-only fact tables for durable ingestion and replay-friendly modeling
• PostgreSQL COPY for efficient bulk ingest

Storage and secrets

• Garage for S3-compatible object storage
• OpenBao for secret storage and secret distribution

Identity

• Dev auth: Samba AD + IdP
• Cloud auth: Google Workspace OIDC

Observability

• Vector for log and event shipping
• Prometheus / Grafana for metrics and dashboards

Platform operations

• K3s / Kubernetes
• Helm
• Argo CD
• Ansible
• OpenTofu

---

Ingestion model

Prole is designed around deterministic, replayable ingestion.

Key patterns:

• SQLite delta cartridges as portable input units
• append-only fact tables for auditability and recovery
• PostgreSQL COPY for high-throughput loading
• queue-driven workers using SKIP LOCKED
• idempotent ingestion so retries are safe
• shard-based deployment so data movement stays deliberate and bounded

This makes the platform well suited to environments where data may arrive in batches, be transferred physically, or need careful replay and provenance.

---

Architecture at a glance

flowchart LR
    U["Users / Operators"]
    A["Next.js App"]
    W["prole-agent"]
    PG["CloudNativePG / PostgreSQL"]
    OBJ["Garage Object Store"]
    SEC["OpenBao"]
    AUTH["Auth: Samba AD / Google Workspace OIDC"]
    OBS["Vector / Prometheus / Grafana"]
    K8S["K3s / Kubernetes"]

    U --> A
    A --> PG
    A --> OBJ
    A --> SEC
    A --> AUTH
    W --> PG
    W --> OBJ
    W --> SEC
    K8S --> A
    K8S --> W
    K8S --> PG
    K8S --> OBJ
    K8S --> SEC
    K8S --> OBS

---

Deployment model

Prole favors simple, understandable deployment over excessive platform ceremony.

Typical characteristics:

• Kubernetes-native deployment
• lightweight K3s-friendly footprint
• HA where it matters
• shard-oriented layout instead of one giant control surface
• GitOps-friendly operations
• support for small clusters, including Pi-based or edge environments

---

Use cases

Prole is a good fit for teams that need:

• a PostgreSQL-centered application stack inside a disconnected environment
• a self-hosted substrate for Supabase-style internal platforms
• ingestion from offline or intermittently connected sources
• reproducible deployment on small Kubernetes clusters
• strong control over secrets, storage, and identity boundaries

---

Project principles

• Air-gap first
• Postgres first
• Simple over ornate
• Deterministic ingestion
• Kubernetes-native
• Shard-friendly
• Operationally boring where possible

---

Repository scope

This repository contains the infrastructure and platform materials used to stand up Prole components, including Kubernetes deployment, database operations, storage, auth, observability, and supporting services.

As the project evolves, this README should stay focused on:

• what Prole is
• why it exists
• the major building blocks
• the deployment model
• the operational philosophy

Detailed setup docs, cluster procedures, and host-specific notes should live in dedicated documents under docs/, ops/, k8s/, or role-specific subdirectories rather than expanding this file indefinitely.

---

Status

Prole is an actively evolving platform stack aimed at practical self-hosted and air-gapped operation.

Expect the architecture to continue being refined toward:

• cleaner bootstrapping
• better shard isolation
• smoother rejoin/reset behavior for cluster nodes
• clearer service boundaries
• improved onboarding and operations documentation

---

License

Add the project license here.