c743416ded
Mirror the auto-indexed per-host pattern for a new docs/services/ category, seeded with the six things currently deployed on or around makerfloss.eu: docs, slides, forgejo, gandi-dns, marp, mermaid. Generator/hook generalisation: - scripts/gen_overview.py: replace the hardcoded `hostname` check with a configurable `key_field` (default: hostname). Add a generic `key-link` column kind (replaces the old `hostname-link`) and a `url-link` kind that renders the value as a clickable link. - scripts/overview_config.yml: declare hardware's key_field, then add a `services` block (key_field=name, its own kind/status enums, grouped by kind for the index table). - scripts/mkdocs_hooks.py: route by `page.file.src_uri` so each hardware/* page gets a "Specs" table and each services/* page gets a "Service" table; both share the helpers in gen_overview. Wiring: - Makefile: docs-index and docs-check now regenerate and drift-check both indices. - .forgejo/workflows/docs.yml: same on the CI runner. - mkdocs.yml: add Services to nav. - README.md, CLAUDE.md: list services/ in the repo-layout block. Co-Authored-By: Claude Opus 4.7 (1M context) <noreply@anthropic.com>
51 lines
2.6 KiB
Markdown
51 lines
2.6 KiB
Markdown
# CLAUDE.md
|
|
|
|
This file provides guidance to Claude Code (claude.ai/code) when working with code in this repository.
|
|
|
|
## Project Overview
|
|
|
|
This is a **documentation-only repository** for the MakerFLOSS initiative at Orange Makerspace — a bi-weekly FLOSS jam-session community focused on self-hosted, open-source infrastructure. There is no build system, test suite, or application code.
|
|
|
|
## Working Norms
|
|
|
|
From `notes/todo/2026-04-14-todo.md`:
|
|
|
|
- **Language**: English for code, docs, commits (meeting notes may be in Danish)
|
|
- **Git**: Trunk-based development, feature branches, simple commit messages
|
|
- **Environments**: Containerized and reproducible
|
|
- **Hardware**: All setups documented with README + labeled physically
|
|
- **AI**: Allowed but reviewed; no secrets in commits
|
|
- **Decisions**: Lightweight markdown decision logs
|
|
- **License**: FLOSS by default
|
|
- **Filenames**: ASCII lowercase, kebab-case (`like-this.md`), English regardless of content language. Dated docs use an ISO prefix joined with a hyphen: `YYYY-MM-DD-label.md`. Hostnames are the exception — `docs/hardware/*.md` must equal the host's `hostname` (enforced by `scripts/gen_overview.py`).
|
|
|
|
## Repository Structure
|
|
|
|
```
|
|
docs/ # everything here is built and shipped to docs.makerfloss.eu
|
|
hardware/ # auto-indexed per-host frontmatter (mf00..mf03, makerfloss.eu)
|
|
services/ # auto-indexed per-service frontmatter (docs, forgejo, …)
|
|
infrastructure/ # labdesign, VPS/DNS, etc.
|
|
presentations/ # Marp decks (build-slides.sh)
|
|
notes/ # repo-only working material, not built
|
|
meetings/ # meeting notes (Danish allowed)
|
|
todo/ # task lists, working norms, wishlist, services
|
|
dev/ # internal plans/ and specs/
|
|
communications/ # community comms artifacts (Facebook posts, etc.)
|
|
sandbox/ # scratch / pipeline fixtures (e.g. test-mermaid.md)
|
|
```
|
|
|
|
## Infrastructure
|
|
|
|
The MakerFLOSS infrastructure is managed externally via the **AnsibleBaobabV4** Ansible project (hosted at `forgejo.nyumbani.baobab.band/sjat/AnsibleBaobabV4`). Key facts:
|
|
|
|
- **VPS**: `88.99.32.236`, SSH on port `7576`
|
|
- **Forgejo** (self-hosted git forge): `https://forgejo.makerfloss.eu`, SSH on port `7577`
|
|
- **Reverse proxy**: Traefik with automatic Let's Encrypt TLS
|
|
- **DNS**: `makerfloss.eu` via Gandi.net, managed declaratively through Ansible (`play_dns.yml --limit makerfloss`)
|
|
- **DNS records must never be edited directly** in the Gandi panel — always edit `host_vars/makerfloss.yml` in AnsibleBaobabV4
|
|
|
|
Clone via Forgejo SSH:
|
|
```bash
|
|
git clone ssh://git@forgejo.makerfloss.eu:7577/<user>/<repo>.git
|
|
```
|