mirror of
https://github.com/dredx/prole.git
synced 2026-09-23 12:03:59 +00:00
2c6df07933
- Add diagnostics/reset/retry logic for stuck monitoring Helm installs\n- Add optional cluster-side node/lease deletion during k3s reset via delegated control-plane\n- Bump prole-db image tag/version to 18-123\n- Update monitoring init unit test for reset/diagnostics path
266 lines
9.6 KiB
Markdown
266 lines
9.6 KiB
Markdown
<div align="center">
|
|
<a href="https://svc.prole.org"><pre>
|
|
# ###########################
|
|
# ╭──────────────────────╮ #
|
|
# │ _ │ #
|
|
# │ _ __ _ _ ___| |___ │ #
|
|
# │ | '_ \ '_/ _ \ / -_) │ #
|
|
# │ | .__/_| \___/_\___| │ #
|
|
# │ |_| │ #
|
|
# ╰──────────────────────╯ #
|
|
# ###########################
|
|
</pre></a>
|
|
</div>
|
|
|
|
# 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
|
|
|
|
<div align="center">
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
</div>
|
|
|
|
---
|
|
|
|
## 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.
|