LiberoStack

The ultra-lightweight, zero-JS, self-hosted alternative to expensive SaaS membership platforms. Run your automated subscription business on a $5 VPS with absolute data sovereignty, cryptographic webhook security, and a production-grade async fulfillment engine.

LiberoStack is the core runtime of Sovereign Hub: a compact FastAPI application that accepts verified payment events, activates subscriptions, delivers Telegram/Discord access, handles churn, and gives the owner a server-rendered control panel with real-time operational visibility.

Why LiberoStack

Most membership platforms rent you convenience at the cost of control. LiberoStack flips that model:

• Your data stays in your PostgreSQL database.
• Your payment events are verified cryptographically before they touch storage.
• Your delivery artifacts live in PostgreSQL JSONB instead of brittle vendor-specific tables.
• Your admin UI is pure server-side rendering, so it stays fast on tiny VPS instances.
• Your worker runs inside the same app process, with no Redis, Celery, or external queue required.

Architecture Highlights

High Performance SSR

The control panel and customer portal are rendered with FastAPI, Jinja2, and Tailwind CSS. There are no heavy client-side JavaScript frameworks, hydration costs, or front-end build steps.

Pure SVG Analytics

MRR and processed checkout revenue charts are calculated server-side and rendered as inline SVG. The chart pipeline uses SQLAlchemy 2.0 queries, PostgreSQL JSONB extraction, and deterministic vector paths, loading in microseconds without Chart.js or other browser dependencies.

Cryptographic Gateway Ingest

Stripe webhooks are verified with the official Stripe SDK using the raw signed request body before persistence.

BTCPay Server webhooks are verified with HMAC-SHA256 signatures over the raw payload bytes and deduplicated by invoiceId.

Telegram webhook updates are protected through Telegram's X-Telegram-Bot-Api-Secret-Token validation header, with runtime support for local polling and production webhooks.

Bulletproof Resiliency

The asynchronous worker processes webhook events out of PostgreSQL with row-level locking, exponential backoff retries, and a Dead Letter Queue.

Retry timing follows:

delay = 2 ** retry_count

When an event exhausts retries, it lands in the interactive DLQ panel where the owner can inspect the stack trace and force a replay directly from the Admin UI.

JSONB Fulfillment Ledger

Subscriptions use a flexible delivery_artifacts JSONB column for provider IDs, generated invite links, revocation flags, checkout IDs, and future delivery data. This keeps the schema stable while integrations evolve.

What It Ships With

• FastAPI async application runtime
• SQLAlchemy 2.0 async models
• PostgreSQL JSONB storage
• Alembic migrations
• Stripe webhook verification
• BTCPay Server webhook verification
• Billgang webhook ingestion scaffolding
• Telegram delivery and revocation
• Telegram polling/webhook runtime switch
• Discord OAuth2 fulfillment scaffolding
• Async webhook worker
• Exponential retry and DLQ handling
• Server-rendered Admin Dashboard
• Customer Magic Portal
• Pure SVG revenue analytics
• Docker production image
• Docker Compose production stack
• Caddy automatic HTTPS reverse proxy
• One-click install.sh production bootstrap

Quick Start: Production VPS

Use a fresh Ubuntu 22.04 or 24.04 VPS with ports 80 and 443 open, and point an A record for your domain to the VPS IP.

Then run:

git clone https://github.com/Iloopp/Sovereign_Hub.git && cd Sovereign_Hub && chmod +x install.sh && ./install.sh

The installer will:

• create .env from .env.example if needed
• set ENV=production
• configure Docker networking for PostgreSQL
• generate a secure POSTGRES_PASSWORD
• generate a secure ADMIN_TOKEN
• generate a secure TELEGRAM_WEBHOOK_SECRET
• prompt for APP_DOMAIN
• set APP_BASE_URL=https://your-domain
• force TELEGRAM_BOT_MODE=webhook
• build and start Postgres, FastAPI, and Caddy
• run alembic upgrade head

After deployment, visit:

https://your-domain/api/v1/admin/dashboard?token=YOUR_ADMIN_TOKEN

Local Development

Create a local .env:

cp .env.example .env

Start PostgreSQL:

docker compose up -d postgres

Synchronize the schema for local smoke testing:

python app/scripts/smoke_test.py

Run the FastAPI app and embedded worker:

python app/main.py

For Stripe CLI testing:

stripe listen --forward-to http://localhost:8000/api/v1/webhooks/stripe
stripe trigger checkout.session.completed

Environment Variables

Variable	Required	Description
PROJECT_NAME	No	FastAPI application title.
ENV	Yes	development or production. Production enforces stricter webhook behavior.
APP_DOMAIN	Production	Public domain used by Caddy and production webhook URLs.
APP_BASE_URL	Yes	Public base URL for OAuth callbacks and Telegram webhook registration.
ADMIN_TOKEN	Yes	Owner token for protected Admin API and dashboard routes.
POSTGRES_SERVER	Yes	Database host and port, e.g. localhost:5433 locally or postgres:5432 in Docker.
POSTGRES_USER	Yes	PostgreSQL username.
POSTGRES_PASSWORD	Yes	PostgreSQL password. Generated by install.sh in production.
POSTGRES_DB	Yes	PostgreSQL database name.
STRIPE_WEBHOOK_SECRET	Production	Stripe endpoint signing secret from Stripe CLI or Dashboard.
BILLGANG_WEBHOOK_SECRET	Optional	Billgang HMAC secret for webhook verification.
BTCPAY_WEBHOOK_SECRET	Optional	BTCPay webhook secret used for HMAC-SHA256 signature verification.
BTCPAY_STORE_ID	Optional	BTCPay store ID used for operational context and delivery artifacts.
BTCPAY_SERVER_URL	Optional	Public or private BTCPay Server URL for integration metadata.
TELEGRAM_BOT_TOKEN	Optional	Telegram BotFather token for access delivery and bot runtime.
TELEGRAM_CHAT_ID	Optional	Default Telegram group/channel ID for invite links and revocation.
TELEGRAM_BOT_MODE	Yes	polling for local development, webhook for production.
TELEGRAM_WEBHOOK_SECRET	Production	Secret validated from X-Telegram-Bot-Api-Secret-Token.
DISCORD_BOT_TOKEN	Optional	Discord bot token for role assignment/revocation.
DISCORD_GUILD_ID	Optional	Default Discord guild/server ID.
DISCORD_CLIENT_ID	Optional	Discord OAuth2 client ID.
DISCORD_CLIENT_SECRET	Optional	Discord OAuth2 client secret.
DISCORD_REDIRECT_URI	Optional	Explicit Discord callback URL override.

Core Routes

Route	Purpose
GET /health	Lightweight service health check.
POST /api/v1/webhooks/stripe	Verified Stripe event ingestion.
POST /api/v1/webhooks/btcpay	Verified BTCPay Server invoice event ingestion.
POST /api/v1/webhooks/billgang	Billgang event ingestion.
POST /api/v1/webhooks/telegram	Telegram webhook update ingestion.
GET /api/v1/portal/claim/{subscription_id}	Customer access portal.
GET /api/v1/admin/dashboard?token=...	Owner control panel.
POST /api/v1/admin/events/{event_id}/retry	DLQ rescue and replay.

Admin Dashboard

The control panel is intentionally SSR-only and lightweight. It includes:

• active member count
• churn/issues count
• estimated MRR from active subscriptions
• plan and integration matrix
• seven-day processed checkout revenue chart
• webhook audit trail
• expandable raw JSON payloads
• expandable Python error traces
• Dead Letter Queue rescue panel with force retry actions

Webhook Processing Lifecycle

provider webhook
  -> cryptographic verification
  -> immutable PostgreSQL JSONB event row
  -> async worker claims row with SKIP LOCKED
  -> business handler activates/cancels subscription
  -> integration dispatcher grants/revokes access
  -> processed, retrying, or dead_letter state

Security Model

• .env is ignored by Git and must never be committed.
• Stripe uses raw-body signature verification.
• BTCPay Server uses HMAC-SHA256 raw-body verification.
• Telegram webhooks validate secret-token headers.
• Admin routes require ADMIN_TOKEN.
• Caddy terminates HTTPS automatically.
• The FastAPI container is exposed only to the internal Docker network in production.
• PostgreSQL credentials and bot tokens are injected at runtime, never baked into images.

License

LiberoStack is released under the MIT License. See LICENSE.