brutsalvadi
0f8bd3dba6
container repo - bincio_wiki/blog/ — new home for all blog content - site/src/content.config.ts — base: '../pages' (was ./src/content/entries) - site/astro.config.mjs — added vite.server.fs.allow: ['..'] so Vite serves files from outside the project root; updated the delete watcher to watch ../pages/ - edit/server.py — default WIKI_PAGES_DIR is now pages (was site/src/content/entries) Content is now versioned in bincio_wiki. The submodule stays clean — it's just the engine.
116 lines
4.6 KiB
Markdown
116 lines
4.6 KiB
Markdown
# bincio_wiki — development notes
|
|
|
|
## Project overview
|
|
|
|
A private wiki for the bincio group of friends. Built on Astro 6 using the
|
|
`brutsalvadi/astro-bloomz` fork as a git submodule at `site/`. Content lives
|
|
in `pages/` and `blog/` at the repo root; Astro loads them via glob loaders
|
|
pointing to `../pages` and `../blog` (outside the submodule). No symlinks.
|
|
|
|
## Directory layout
|
|
|
|
```
|
|
bincio_wiki/
|
|
pages/ wiki content (*.md files the community edits)
|
|
_docs/ software documentation (shown as separate section)
|
|
blog/ blog/stories content (*.md files)
|
|
site/ Astro 6 app (git submodule → brutsalvadi/astro-bloomz)
|
|
edit/ FastAPI edit server (Python, port 8001)
|
|
pyproject.toml Python dependencies (managed by uv)
|
|
uv.lock uv lockfile (committed)
|
|
scripts/ dev.sh — starts both Astro and FastAPI together
|
|
docs/ repo-level documentation (not served as wiki pages)
|
|
```
|
|
|
|
## Running locally
|
|
|
|
```bash
|
|
bash scripts/dev.sh # Astro only (port 4321)
|
|
bash scripts/dev.sh --edit # Astro + FastAPI edit sidecar (port 8001)
|
|
```
|
|
|
|
Python dependencies are managed by `uv`. `uv sync` is called automatically
|
|
by `dev.sh --edit` — no manual setup needed. To add a dependency:
|
|
`uv add <package>` (updates `pyproject.toml` and `uv.lock`).
|
|
|
|
## Content architecture
|
|
|
|
- Wiki pages: `pages/*.md` (IDs in Astro content store are the bare filename
|
|
without extension, e.g. `digital-garden`)
|
|
- Docs section: `pages/_docs/*.md` (IDs start with `_docs/`)
|
|
- Blog/stories: `blog/*.md`
|
|
- Bonsai index: stored in `site/src/content/index/` — the `i.bonsai.md` file
|
|
defines the semantic tree structure
|
|
- The homepage (`site/src/pages/index.astro`) splits entries by `_docs/` prefix
|
|
into "Pagine recenti" and "Documentazione" sections
|
|
|
|
## Astro 6 content layer notes
|
|
|
|
- Collections use glob loaders in `site/src/content.config.ts`
|
|
- `entries` collection base is `../pages` (relative to `site/`), resolving to
|
|
`bincio_wiki/pages/`. Vite is configured with `server.fs.allow: ['..']` to
|
|
permit serving files from outside the project root.
|
|
- `blog` collection base is `../blog` (same pattern)
|
|
- `index` collection base is `./src/content/index` (stays inside `site/`)
|
|
- Custom `generateId` on `entries` and `index` — see `content.config.ts` for
|
|
details. `index` preserves dots so `i.bonsai` is not mangled by githubSlug.
|
|
- Use `entry.id` not `entry.slug`
|
|
- Use `import { render } from 'astro:content'; render(entry)` not `entry.render()`
|
|
|
|
## Language / i18n
|
|
|
|
Italian is the default language. All documentation in `pages/_docs/` is in
|
|
Italian. Technical terms (WikiRefs, Astro, plugin names, wikilink syntax,
|
|
code) stay in English. See `docs/lingua.md` for the full rationale.
|
|
|
|
## Authentication
|
|
|
|
### Current approach (same as bincio_activity)
|
|
|
|
**Not yet implemented in bincio_wiki** — pending.
|
|
|
|
Planned pattern:
|
|
- nginx serves the static Astro build publicly (no nginx-level auth)
|
|
- Every Astro page layout calls `GET /api/me` on load
|
|
- If the API returns 401/error, the page JS redirects to `/login/`
|
|
- FastAPI (`edit/server.py`) handles sessions: SQLite users table, bcrypt
|
|
passwords, HTTP-only session cookie
|
|
- Login page at `/login/` — a static Astro page that POSTs credentials to
|
|
`/api/auth/login`
|
|
|
|
### Security assessment
|
|
|
|
This is **client-side enforcement only**. The HTML is technically accessible
|
|
to anyone who:
|
|
- Uses `curl` or `wget` directly
|
|
- Disables JavaScript in the browser
|
|
- Views page source
|
|
|
|
For bincio_wiki this is an acceptable tradeoff. The content is community
|
|
memories and shared activities (not financial/medical data), members are not
|
|
adversarial, and the goal is keeping casual visitors and search engine crawlers
|
|
out — not resisting determined attackers.
|
|
|
|
### Future: making specific pages public
|
|
|
|
With this architecture, making a page public later is trivial: just use a
|
|
layout variant that skips the `/api/me` check. No nginx changes needed since
|
|
nginx already serves everything publicly at the static file level.
|
|
|
|
For stricter enforcement on genuinely sensitive pages, the alternative is
|
|
**Astro SSR** with a server middleware that checks the session cookie before
|
|
rendering any HTML. This would require migrating from static output to SSR
|
|
mode — a bigger change, not warranted for now.
|
|
|
|
### VPS deployment target
|
|
|
|
Debian 12 VPS. nginx serves the built site from `/var/www/bincio/wiki/`.
|
|
FastAPI proxied from `localhost:8001` via nginx `location /api/ { proxy_pass }`.
|
|
See `docs/vps.md` for full nginx config and deployment steps.
|
|
|
|
## Git conventions
|
|
|
|
- No `Co-Authored-By: Claude` trailers in commits
|
|
- Commit messages in English
|
|
- Do not push without explicit user instruction
|