From 629afa1c8db9fbe9ea1d464e4237443f3f380481 Mon Sep 17 00:00:00 2001 From: Frederic Cabassut Date: Mon, 9 Mar 2026 02:20:07 +0100 Subject: [PATCH] docs: add OAuth/auth docs and install instructions in README Co-Authored-By: Claude Opus 4.6 --- README.md | 36 ++++++++++++++++++++++++++++++++--- docs/ARCHITECTURE.md | 2 +- docs/DEPLOYMENT.md | 45 ++++++++++++++++++++++++++++++++++++++++++++ docs/FEATURES.md | 20 +++++++++++++++++--- 4 files changed, 96 insertions(+), 7 deletions(-) diff --git a/README.md b/README.md index 5eb71c7..400774e 100644 --- a/README.md +++ b/README.md @@ -11,7 +11,7 @@ A self-hostable, offline-first note-taking app inspired by Google Keep. Part of the [Bretzel](https://bretzel.app) app universe. -## Quick Start +## Install ### Docker (Recommended) @@ -19,7 +19,37 @@ A self-hostable, offline-first note-taking app inspired by Google Keep. Part of docker compose up -d ``` -Open http://localhost:3000 and set your password on first visit. +Open http://localhost:3000 and create your admin account on first visit. + +#### With OAuth (optional) + +```yaml +# docker-compose.yml +services: + crumbs: + image: ghcr.io/bretzel-app/crumbs:latest + ports: + - "3000:3000" + volumes: + - crumbs-data:/data + environment: + - ORIGIN=https://notes.example.com + - AUTH_GOOGLE_ID=your-google-client-id + - AUTH_GOOGLE_SECRET=your-google-client-secret + restart: unless-stopped + +volumes: + crumbs-data: +``` + +### Manual (Node.js) + +```bash +git clone crumbs && cd crumbs +pnpm install +pnpm build +DATABASE_URL=./data/crumbs.db ORIGIN=http://localhost:3000 node build +``` ### Development @@ -43,7 +73,7 @@ pnpm build # Production build - Full-text search across titles, content, and tags - PWA — installable, works offline via IndexedDB + LWW CRDT sync - MCP server — let AI assistants (Claude Code, etc.) manage your notes -- Single-user password auth (Argon2) + API keys for MCP access +- Multi-user auth (Argon2) with optional OAuth/SSO (Google, GitHub, OIDC) - Docker deployment with a single command See [docs/FEATURES.md](docs/FEATURES.md) for detailed feature documentation. diff --git a/docs/ARCHITECTURE.md b/docs/ARCHITECTURE.md index 952a501..9898589 100644 --- a/docs/ARCHITECTURE.md +++ b/docs/ARCHITECTURE.md @@ -92,7 +92,7 @@ For a single-user app with multiple devices: See `src/lib/server/db/schema.ts` for the complete Drizzle schema. Key tables: -- `users` - Single user (password hash) +- `users` - User accounts (password hash, OAuth provider link, role) - `sessions` - Auth sessions (30-day TTL) - `notes` - Core note data with version tracking - `tags` - Unique tag names diff --git a/docs/DEPLOYMENT.md b/docs/DEPLOYMENT.md index 222c7be..7a9a10b 100644 --- a/docs/DEPLOYMENT.md +++ b/docs/DEPLOYMENT.md @@ -100,6 +100,8 @@ node build ## Environment Variables +### Core + | Variable | Default | Description | |----------|---------|-------------| | `DATABASE_URL` | `./data/crumbs.db` | SQLite database path | @@ -108,6 +110,49 @@ node build | `PORT` | `3000` | HTTP port | | `NODE_ENV` | `development` | Set to `production` for deployment | +### OAuth Providers (optional) + +Enable social login by setting the client ID and secret for any provider. Users who sign in via OAuth are created automatically (invite-only when combined with admin approval). + +| Variable | Description | +|----------|-------------| +| `AUTH_GOOGLE_ID` | Google OAuth client ID | +| `AUTH_GOOGLE_SECRET` | Google OAuth client secret | +| `AUTH_GITHUB_ID` | GitHub OAuth client ID | +| `AUTH_GITHUB_SECRET` | GitHub OAuth client secret | +| `AUTH_OIDC_ISSUER` | Generic OIDC issuer URL (e.g. `https://accounts.example.com`) | +| `AUTH_OIDC_ID` | OIDC client ID | +| `AUTH_OIDC_SECRET` | OIDC client secret | +| `AUTH_OIDC_NAME` | Display name for the OIDC button (default: "SSO") | + +**Callback URLs** — register these in your provider's dashboard: + +| Provider | Callback URL | +|----------|-------------| +| Google | `https://your-domain/api/auth/callback/google` | +| GitHub | `https://your-domain/api/auth/callback/github` | +| OIDC | `https://your-domain/api/auth/callback/oidc` | + +#### Docker example with Google OAuth + +```yaml +services: + crumbs: + image: ghcr.io/bretzel-app/crumbs:latest + ports: + - "3000:3000" + volumes: + - crumbs-data:/data + environment: + - ORIGIN=https://notes.example.com + - AUTH_GOOGLE_ID=123456789.apps.googleusercontent.com + - AUTH_GOOGLE_SECRET=GOCSPX-xxxxxxxxxxxxx + restart: unless-stopped + +volumes: + crumbs-data: +``` + ## Health Check The Docker image includes a health check that pings `/login`: diff --git a/docs/FEATURES.md b/docs/FEATURES.md index b88afaf..0d0613b 100644 --- a/docs/FEATURES.md +++ b/docs/FEATURES.md @@ -86,12 +86,26 @@ - Clear search to restore original view - Case-insensitive matching -### Single-User Auth -- First-run setup: create password (min 8 chars) +### Authentication +- Multi-user support with role-based access (admin / user) +- First-run setup: create admin account (min 8 chars password) - Argon2 password hashing (industry standard) - Session-based auth with 30-day expiry +- Active session management (view, revoke individual or all other sessions) - All routes protected except /login and /setup -- Logout clears session +- Account deletion with password confirmation + +### OAuth / SSO +- Optional social login via Google, GitHub, or generic OIDC +- OAuth users created automatically on first sign-in +- Invite-only mode when combined with admin controls +- Configure via environment variables (`AUTH_GOOGLE_ID`, `AUTH_GITHUB_ID`, `AUTH_OIDC_ISSUER`, etc.) + +### User Management (admin) +- Admin dashboard to create, list, and delete users +- Assign roles (admin / user) +- Reset passwords for any user +- Revoke all sessions (force logout) for any user ### PWA / Offline-First - Installable as standalone app