# 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`.

## Browsing this documentation

The docs dependency group is declared in `pyproject.toml` and is separate from the runtime dependencies.

```bash
# Live-reload server at http://127.0.0.1:8000
uv run --group docs mkdocs serve

# Build static output to site/
uv run --group docs mkdocs build
```

## Adding Python dependencies

```bash
uv add <package>          # runtime dep — updates pyproject.toml and uv.lock
uv add --group docs <package>  # docs-only dep
```

## 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`).