Add MkDocs documentation: architecture, deployment, development, decisions

2026-05-08 10:07:20 +02:00
parent fd2d81328f
commit ccec23c3a3
10 changed files with 591 additions and 102 deletions
@@ -0,0 +1,88 @@
+# Getting Started
+
+## Prerequisites
+
+- **Node.js** ≥ 18 and **npm**
+- **Python** ≥ 3.11
+- **uv** — Python package manager (`curl -LsSf https://astro.sh/uv/install.sh | sh` or `pip install uv`)
+- A running instance of **bincio_activity** with a seeded dev database, or a manually created `instance.db`
+
+## Shared database
+
+The wiki shares its user/session/invite database with `bincio_activity`. For local development, the default path is `/tmp/bincio_dev_test/instance.db`.
+
+The easiest way to seed it is to run `bincio_activity`'s dev setup script:
+
+```bash
+cd ../bincio_activity
+uv run python scripts/dev_test.py --fresh
+```
+
+Alternatively, set `SHARED_DB_PATH` to point to an existing `instance.db`:
+
+```bash
+export SHARED_DB_PATH=/path/to/instance.db
+```
+
+## Running locally
+
+```bash
+# Clone with submodule
+git clone --recurse-submodules <repo-url>
+cd bincio_wiki
+
+# Astro dev server only (port 4321)
+bash scripts/dev.sh
+
+# Astro + FastAPI sidecar (ports 4321 + 8001)
+bash scripts/dev.sh --edit
+```
+
+`uv sync` is called automatically by `dev.sh --edit` — no manual Python setup needed.
+
+The Astro dev server proxies all `/api/`, `/pages/`, `/stories/`, `/assets/`, and `/rebuild` requests to `http://localhost:8001`.
+
+## Adding Python dependencies
+
+```bash
+uv add <package>   # updates pyproject.toml and uv.lock
+```
+
+## Adding JS dependencies
+
+```bash
+cd site
+npm install <package>
+```
+
+## Submodule notes
+
+The `site/` directory is a git submodule pointing to `brutsalvadi/astro-bloomz`. To update it:
+
+```bash
+cd site
+git pull origin main
+cd ..
+git add site
+git commit -m "Update site submodule"
+```
+
+To push submodule changes to the VPS independently:
+
+```bash
+cd site && git push vps main
+```
+
+## Environment variables
+
+| Variable | Default | Description |
+|----------|---------|-------------|
+| `SHARED_DB_PATH` | `/tmp/bincio_dev_test/instance.db` | Path to shared SQLite DB |
+| `WIKI_PAGES_DIR` | `pages` | Pages directory (relative to repo root) |
+| `WIKI_STORIES_DIR` | `blog` | Blog directory |
+| `WIKI_ASSETS_DIR` | `assets` | Assets directory |
+| `WIKI_WEBROOT` | _(unset)_ | If set, rsync `dist/` here after rebuild |
+| `SESSION_DOMAIN` | _(unset)_ | Cookie domain (e.g. `.bincio.org` in prod) |
+| `GIT_DIR` | _(unset)_ | Bare repo path (VPS only) |
+
+In production all of these are set in the systemd service file (`deploy/vps/bincio-wiki.service`).