Merge branch 'main' of https://github.com/explodinglabs/superstack

Author: bcb

README.md

@@ -24,19 +24,21 @@ flowchart TD
 
 ## 🚀 Quick Start
 
-1. **Clone SuperStack and start the stack:**
+1. Click [Use this
+   template](https://github.com/explodinglabs/superstack/generate) and create a
+   new repository on Github.
+
+2. Clone your new repository and start SuperStack:
 
 ```sh
-git clone https://github.com/explodinglabs/superstack myapp
+git clone https://github.com/yourname/myapp.git
 cd myapp
 cp example.env .env
 docker compose up -d
 ```
 
-2. **Explore your API**
-
-Open [http://localhost:8000/openapi/](http://localhost:8000/openapi/) in your
-browser to view and test endpoints using Swagger UI.
+Open [http://localhost:8000/openapi/](http://localhost:8000/openapi/) to view
+your Swagger UI.
 
 ## 📚 Full Documentation
 

docs/authentication.md

@@ -20,8 +20,8 @@ Edit `postgres/Dockerfile` to build and install the extension:
 
 ```sh
 RUN apt-get update && apt-get install -y \
- build-essential \
- postgresql-server-dev-17
+  build-essential \
+  postgresql-server-dev-17
 
 # pgjwt - used by auth schema
 COPY ./pgjwt /pgjwt
@@ -31,10 +31,11 @@ RUN make && make install
 WORKDIR /var/lib/postgresql
 ```
 
-Then rebuild:
+Then rebuild the Postgres image and recreate the container:
 
 ```sh
 docker compose build postgres
+docker compose up -d postgres
 ```
 
 ## ➡️ 2. Add Migrations
@@ -44,7 +45,9 @@ docker compose build postgres
 Add this to a migration file like `01-extensions.sql`:
 
 ```sql
--- pgcrypto adds public.crypt used in auth.encrypt_pass
+/* pgcrypto adds public.crypt used in auth.encrypt_pass pgjwt also needs this
+so it must be loaded first. pgcrypto is built into Postgres, so no need to
+install it. */
 create extension pgcrypto;
 
 -- pgjwt adds public.sign used in auth.generate_access_token
@@ -212,7 +215,7 @@ commit;
 
 ### 👮 Grant Permissions
 
-Add another migration such as `99-roles_and_grants.sql`:
+Add another migration such as `99-grants.sql`:
 
 ```sql
 begin;
@@ -241,14 +244,57 @@ applied.
 Add the auth schema to Postgres in `compose.yaml`:
 
 ```yaml
-PGRST_DB_SCHEMAS: api,auth
+postgrest:
+  environment:
+    PGRST_DB_SCHEMAS: api,auth
 ```
 
-✅ Usage
+And recreate the PostgREST container:
 
-Explain that all auth endpoints must have a certain header.
+```sh
+docker compose up -d postgrest
+```
+
+## ✅ Usage
+
+To use the `auth` schema, requests [must include a
+header](https://docs.postgrest.org/en/stable/references/api/schemas.html#multiple-schemas).
+
+GET and HEAD requests should include the header:
+
+```
+Accept-Profile: auth
+```
+
+Other methods (POST, PATCH, PUT and DELETE) should include:
+
+```
+Content-Profile: auth
+```
 
-Show example of using each endpoint.
+### Examples
+
+Login:
+
+```sh
+curl \
+  -H "Content-Profile: auth" \
+  -H "Content-Type: application/json" \
+  --data '{"user_": "demo", "pass": "demo"}' \
+  http://localhost/rpc/login
+```
+
+Get the refresh token inserted when logged in:
+
+```sh
+bin/postgres psql -c 'select token from auth.refresh_token order by created_at desc limit 1'
+```
+
+Refresh the access token and extract the new token from the Set-Cookie header:
+
+```sh
+export ACCESS_TOKEN=$(curl --silent -i -X POST -H 'Cookie: refresh_token='$REFRESH_TOKEN'; HttpOnly' http://localhost/rpc/refresh_token |sed -nE 's/^Set-Cookie: access_token=([^;]*).*/\1/p')
+```
 
 - POST-ing a user.
 - `/rpc/login`

docs/gettingstarted.md

@@ -3,51 +3,39 @@
 SuperStack uses Docker, so make sure [Docker is
 installed](https://docs.docker.com/get-docker/) before you begin.
 
-## 1. Clone SuperStack
+## 1. Get SuperStack
 
-```sh
-git clone https://github.com/explodinglabs/superstack myapp
-cd myapp
-```
+### Option 1: Use the Template (Recommended)
 
-<details>
-<summary>Click here to see how to change this clone to point "origin" to your own hosted repository (Recommended)</summary>
+The easiest way to get started:
 
-Rename "origin" to "upstream":
+1. Click [Use this
+   template](https://github.com/explodinglabs/superstack/generate) on GitHub.
+2. Create a new repository (e.g. `myapp`) from the template.
+3. Clone it to your machine:
 
 ```sh
-git remote rename origin upstream
+git clone https://github.com/yourname/myapp.git
+cd myapp
 ```
 
-This way you can still upgrade to a more recent SuperStack with:
-
-```sh
-git pull upstream main
-```
+### Option 2: Clone and Track Upstream (Advanced)
 
-Add your own code repository:
+If you want to keep SuperStack’s Git history and pull upstream changes later:
 
 ```sh
+git clone https://github.com/explodinglabs/superstack.git myapp
+cd myapp
+git remote rename origin upstream
 git remote add origin https://github.com/yourname/myapp
 ```
 
-Now you can pull/push to your own repo as normal:
+You can now pull upstream changes with:
 
 ```sh
-git pull
-git push origin head
+git pull upstream main
 ```
 
-<h3>Why not just fork SuperStack?</h3>
-
-Because you can't make a fork private.
-
-<h3>Why not make SuperStack a template repo?</h3>
-
-Because then you can't pull from upstream SuperStack.
-
-</details>
-
 ## 2. Configure Environment Variables
 
 Copy the example file:
@@ -56,8 +44,8 @@ Copy the example file:
 cp example.env .env
 ```
 
-> ⚠️ The .env file is for local development only. For remote deployments,
-> set environment variables using CI/CD or inline in the `docker compose up` command (be sure to avoid saving secrets in shell history).
+> ⚠️ **The .env file is for local development only.** Don't store real secrets
+> in production — use CI/CD environment variables or a secrets manager.
 
 ## 3. Start the Stack
 
@@ -67,19 +55,20 @@ docker compose up -d
 
 That's it – your backend is live.
 
-You can now open [localhost:8000/openapi/](http://localhost:8000/openapi/)
-to explore your API.
+You can now open
+[http://localhost:8000/openapi/](http://localhost:8000/openapi/) to explore
+your API.
 
 ---
 
 ## 🧩 What Just Happened?
 
 SuperStack automatically:
 
-- Starts a fresh **Postgres** database
-- Applies initial **migrations**
-- Launches **PostgREST** and **Swagger UI**
-- Serves everything through **Caddy**
+1. Starts a fresh Postgres database
+2. Applies initial migrations
+3. Launches PostgREST and Swagger UI
+4. Serves everything through Caddy
 
 ```mermaid
 flowchart TD
@@ -90,14 +79,33 @@ flowchart TD
 
 > 💡 Only Caddy exposes a port – all services are routed through it.
 
-## Nuke everything
+## Project Structure
 
-To wipe your stack and start clean:
+```
+📁 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)  

docs/index.md

@@ -2,9 +2,9 @@
 
 # SuperStack
 
-_SuperStack_ is a lightweight, modular backend powered by PostgreSQL —
-perfect for indie developers, SaaS builders, and teams who want full
-rontrol without the bloat.
+_SuperStack_ is a lightweight, modular backend powered by PostgreSQL — perfect
+for indie developers, SaaS builders, and teams who want full control without
+the bloat.
 
 Spin up a fully working backend in seconds, with zero setup. Just clone and
 run.
@@ -25,11 +25,6 @@ Caddy), making it easy to develop locally or deploy remotely.
 
 ---
 
-## 📚 Documentation
+## 📚 Get Started
 
-- [Getting Started](gettingstarted.md)
-- [Migrations](migrations.md)
-- [Postgres Extensions](extensions.md)
-- [Authentication](authentication.md)
-- [Psql](psql.md)
-- [Deploying to Remote Environments](deploying.md)
+👉 [Continue to Getting Started](gettingstarted.md)

docs/migrations.md

@@ -1,11 +1,10 @@
 # 📜 Migrations
 
-SuperStack includes a simple built-in system for managing database schema
-migrations.
+SuperStack includes a simple system for managing database schema changes.
 
 ## ✍️ Writing Migrations
 
-Place your migration scripts in:
+Place SQL scripts in:
 
 ```
 postgres/migrations/
@@ -14,9 +13,9 @@ postgres/migrations/
 Each file should be:
 
 - A `.sql` file
-- Numbered in order (e.g. `00-init.sql`, `01-extensions.sql`, `02-auth.sql`)
+- Numbered in order (e.g. `00-init.sql`, `01-extensions.sql`, `02-create_auth_schema.sql`)
 - Written in plain SQL
-- But can include environment variables.
+- But can include environment variables
 
 ## ▶️ Applying Migrations
 
@@ -41,22 +40,10 @@ Already-applied scripts are skipped on subsequent runs.
 
 > 💡 `bin/postgres` is short for `docker compose exec postgres`
 
-## 🔄 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.
-
 ## 🔁 Transactions
 
-Use `BEGIN;` and `COMMIT;` to wrap migration files when all included
-statements are transactional. This ensures that all changes are applied
-atomically.
+Use `BEGIN;` and `COMMIT;` to wrap migration files when all included statements
+are transactional. This ensures that all changes are applied atomically.
 
 For example:
 
@@ -78,11 +65,10 @@ create table movie (
 commit;
 ```
 
-> 💡 If your migration script only contains one statement, there's no need
-> to use a transaction, the statement will be auto-committed.
+> 💡 Statements outside of begin/commit are auto-committed.
 
-Avoid wrapping non-transactional operations in a transaction — these will
-cause errors if used inside `BEGIN ... COMMIT`.
+Avoid wrapping non-transactional operations in a transaction — these will cause
+errors if used inside `BEGIN ... COMMIT`.
 
 Examples of non-transactional statements include: