Initial import from superstack repo

Author: bcb

.github/workflows/deploy-docs.yml

@@ -0,0 +1,49 @@
+# ⚠️ This workflow deploys docs to explodinglabs.com
+# It is active only in the official repo. Forks won't trigger deployment.
+name: Build and Deploy MkDocs
+
+on:
+  push:
+    branches:
+      - main # or your main development branch
+
+jobs:
+  deploy:
+    if: github.repository == 'explodinglabs/superstack'
+    runs-on: ubuntu-latest
+
+    steps:
+      - name: Checkout source repo
+        uses: actions/checkout@v3
+
+      - name: Set up Python
+        uses: actions/setup-python@v4
+        with:
+          python-version: 3.x
+
+      - name: Install dependencies
+        run: pip install mkdocs mkdocs-material  mkdocs-mermaid2-plugin
+
+      - name: Build MkDocs site
+        run: mkdocs build
+
+      - name: Clone target repo
+        run: |
+          git clone https://x-access-token:${{ secrets.TARGET_REPO_PAT }}@github.com/explodinglabs/explodinglabs.com.git target-repo
+          rm -rf target-repo/$(basename "$GITHUB_REPOSITORY")
+          mkdir -p target-repo/$(basename "$GITHUB_REPOSITORY")
+          cp -a site/. target-repo/$(basename "$GITHUB_REPOSITORY")/
+        env:
+          GIT_AUTHOR_NAME: GitHub Actions
+          GIT_COMMITTER_NAME: GitHub Actions
+          GIT_AUTHOR_EMAIL: [email protected]
+          GIT_COMMITTER_EMAIL: [email protected]
+
+      - name: Commit and push
+        run: |
+          cd target-repo
+          git config user.name "Exploding Labs Bot"
+          git config user.email "[email protected]"
+          git add .
+          git commit -m "Update site from docs source repo" || echo "No changes to commit"
+          git push

docs/assets/getting-started.mp4

@@ -0,0 +1,68 @@
+# ☁️ Deploying to Remote Environments
+
+SuperStack is Docker-native, so deployment is simple and portable. Here's
+how to deploy it to a remote server.
+
+## ✅ 1. Set Your Image Names
+
+Change the image names to your own (e.g. using your Docker Hub or GitHub
+Container Registry account) in `compose.yaml`, for example:
+
+```yaml
+postgres:
+  image: ghcr.io/youruser/yourapp-postgres
+caddy:
+  image: ghcr.io/youruser/yourapp-caddy
+```
+
+## 🛠️ 2. Build and Push your Images
+
+Build your images locally and push to your registry:
+
+```sh
+docker compose build
+docker compose push
+```
+
+## 📦 3. Deploy the Compose File
+
+The only file needed for SuperStack to work on the remote server is
+`compose.yaml`.
+
+Copy it to your server:
+
+```sh
+scp compose.yaml youruser@yourserver:
+```
+
+## 🚀 4. Launch your Stack
+
+SSH into your server and bring up the stack.
+
+For production, avoid using `.env` files. Instead, set secrets directly:
+
+```sh
+CADDY_PORT=80 \
+PG_USER=admin \
+PG_PASS=supersecret \
+POSTGREST_AUTHENTICATOR_PASS=supersecret \
+JWT_SECRET=your-secret \
+docker compose up -d
+```
+
+> 💡 Avoid leaking secrets by disabling shell history.
+
+Alternatively, use environment injection in your CI/CD.
+
+---
+
+That’s it — your backend is live.
+
+If this is the first time bringing up your stack, the migrations will run
+automatically. Subsequently, to upgrade your app you should:
+
+```sh
+docker compose pull
+docker compose up -d
+docker compose exec postgres migrate
+```

docs/assets/logo.png

@@ -0,0 +1,58 @@
+# 🧩 Postgres Extensions
+
+SuperStack supports PostgreSQL extensions, letting you add powerful
+features like cryptographic functions or JWT handling.
+
+## 🔌 Loading a Built-In Extension
+
+To load a standard extension (like pgcrypto), create a migration file such
+as:
+
+```sql
+-- File: postgres/migrations/01-extensions.sql
+
+create extension pgcrypto;
+```
+
+> ⚠️ `create extension` is non-transactional, so don’t wrap this file in
+> `BEGIN/COMMIT`.
+
+## 🛠️ Building an Extension from Source
+
+Some extensions (like [pgjwt](https://github.com/michelp/pgjwt)) must be
+compiled manually.
+
+### 1. Clone the Extension Source
+
+```sh
+git clone https://github.com/michelp/pgjwt postgres/pgjwt
+```
+
+### 2. Modify the Postgres Dockerfile
+
+Edit `postgres/Dockerfile` to install build tools and compile the
+extension:
+
+```
+RUN apt-get update && apt-get install -y \
+    build-essential \
+    postgresql-server-dev-17
+
+# pgjwt - used by the auth schema
+COPY ./pgjwt /pgjwt
+WORKDIR /pgjwt
+RUN make && make install
+
+# Reset workdir
+WORKDIR /var/lib/postgresql
+```
+
+> 🧼 Set `WORKDIR` back to the default to avoid unintended effects.
+
+### 3. Rebuild the Container
+
+```sh
+docker compose build postgres
+```
+
+That’s it — the extension is now available to load in your migrations.

docs/deploying.md

@@ -0,0 +1,134 @@
+# 🚀 Getting Started
+
+<video controls width="100%">
+  <source src="https://explodinglabs.com/assets/superstack-getting-started.mp4" type="video/mp4">
+  Your browser does not support the video tag.
+  Music: https://www.bensound.com
+  License code: UZG5X7IWWLQOQEU1
+  Artist: : Lunar Years
+</video>
+
+SuperStack uses Docker, so make sure [Docker is
+installed](https://docs.docker.com/get-docker/) before you begin.
+
+## 1. Get SuperStack
+
+### Option 1: Use the Template (Recommended)
+
+The easiest way to get started:
+
+Click [Use this template](https://github.com/explodinglabs/superstack/generate)
+and create a new repository (e.g. `myapp`) on GitHub.
+
+Clone it to your machine:
+
+```sh
+git clone https://github.com/yourname/myapp.git
+cd myapp
+```
+
+### Option 2: Clone and Track Upstream (Advanced)
+
+If you want to keep SuperStack’s Git history and pull upstream changes later,
+clone SuperStack:
+
+```sh
+git clone https://github.com/explodinglabs/superstack.git myapp
+cd myapp
+```
+
+[Create your own repo](https://github.com/new), then:
+
+```sh
+git remote rename origin upstream
+git remote add origin https://github.com/yourname/myapp.git
+git push -u origin main
+```
+
+You can now pull upstream changes with:
+
+```sh
+git pull upstream main
+```
+
+## 2. Configure Environment Variables
+
+Copy the example environment file:
+
+```sh
+cp example.env .env
+```
+
+This `.env` file is used to configure:
+
+- **Secrets** – Passwords, keys, etc.
+- **Ports** – Adjust the exposed ports (specifically, Caddy's) depending on
+  environment or application (you may bring up multiple).
+
+> ⚠️ Important: The .env file is for local development only. Never store real
+> secrets in version control or production. Use CI/CD environment variables or
+> a secrets manager instead.
+
+## 3. Start the Stack
+
+```sh
+docker compose up -d
+```
+
+That's it – your backend is live.
+
+You can now open
+[http://localhost:8000/openapi/](http://localhost:8000/openapi/) to explore
+your API (assuming 8000 is your Caddy port).
+
+---
+
+## 🧩 What Just Happened?
+
+SuperStack automatically:
+
+1. Starts a fresh Postgres database
+2. Applies initial migrations
+3. Launches PostgREST and Swagger UI
+4. Serves everything through Caddy
+
+```mermaid
+flowchart TD
+    Caddy["Caddy (API Gateway)"]
+    Caddy --> Services["Services (PostgREST, Swagger UI + more)"]
+    Services --> Postgres
+```
+
+> 💡 Only Caddy exposes a port – all services are routed through it.
+
+## Project Structure
+
+```
+📁 bin/                  → Helper scripts (e.g. wrappers for CLI tools)
+📁 caddy/                → Custom Caddy configuration and certificates
+📁 docs/                 → Markdown files for SuperStack documentation
+📁 postgres/             → SQL migrations and configuration of the postgres container
+📄 compose.yaml          → Main Docker Compose config
+📄 compose.override.yaml → Optional local overrides (development only)
+📄 example.env           → Example environment variables — copy to `.env`
+📄 LICENSE               → License file (MIT)
+📄 logo.png              → SuperStack logo for README/docs
+📄 mkdocs.yml            → MkDocs configuration for documentation site
+📄 README.md             → Overview and quick start for the repository
+```
+
+## 🔄 Resetting
+
+If you want to start fresh:
+
+```sh
+docker compose down --volumes
+docker compose up -d
+```
+
+This will wipe your database and re-run all migrations from scratch.
+
+## ➕ What's Next?
+
+👉 [Create your database schema with migrations](migrations.md)  
+👉 [Deploy to a remote environment](deploying.md)

docs/extensions.md

@@ -0,0 +1,50 @@
+<style>
+  .logo-responsive {
+    float: right;
+    padding-left: 2em;
+  }
+
+  @media (max-width: 768px) {
+    .logo-responsive {
+      float: none;
+      display: block;
+      margin: 0 auto 2em;
+      padding: 0;
+    }
+  }
+</style>
+
+<img src="assets/logo.png" alt="SuperStack Logo" class="logo-responsive" />
+
+# SuperStack
+
+Jump to:
+[GitHub](https://github.com/explodinglabs/superstack) | [Developer Wiki](https://github.com/explodinglabs/superstack/wiki)
+
+_SuperStack_ is a minimal, modular backend powered by PostgreSQL — perfect for
+indie developers, SaaS builders, and teams who want full rontrol without the
+bloat.
+
+Spin up a fully working backend in seconds. Just clone, run, and start
+building.
+
+---
+
+## 🚀 What Can I Do with SuperStack?
+
+It's perfect for:
+
+- 🧱 Building SaaS apps
+- 💻 Running multiple stacks locally
+- 📦 Easy database migrations
+- 🔧 Customizing your toolchain
+
+Everything runs inside Docker and routes through a single exposed port (via
+Caddy), making it easy to develop locally or deploy remotely.
+
+---
+
+## 📚 What's next?
+
+👉 [Getting Started](gettingstarted.md) – a guide to installing SuperStack and
+launching the stack.