# 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
```mermaid
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.