bincio-wiki/docs/development/getting-started.md

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:

cd ../bincio_activity
uv run python scripts/dev_test.py --fresh

Alternatively, set SHARED_DB_PATH to point to an existing instance.db:

export SHARED_DB_PATH=/path/to/instance.db

Running locally

# 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

uv add <package>   # updates pyproject.toml and uv.lock

Adding JS dependencies

cd site
npm install <package>

Submodule notes

The site/ directory is a git submodule pointing to brutsalvadi/astro-bloomz. To update it:

cd site
git pull origin main
cd ..
git add site
git commit -m "Update site submodule"

To push submodule changes to the VPS independently:

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