brutsalvadi
102 lines
2.7 KiB
Markdown
102 lines
2.7 KiB
Markdown
# 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`).
|