documentation update

This commit is contained in:
2026-08-14 13:48:32 +02:00
parent 9709a73daf
commit a9dda1e2a5
5 changed files with 81 additions and 52 deletions
+4 -5
View File
@@ -12,12 +12,11 @@ Für alle Home-Bereich-Sites (infra, smarthome, code, retro) gilt ab jetzt ein k
Das ist ein wichtiger Unterschied zu v3/v4: nicht "alles identisch", sondern **Header konsistent, Content-Layout pro Subseite flexibel**. Das ist ein wichtiger Unterschied zu v3/v4: nicht "alles identisch", sondern **Header konsistent, Content-Layout pro Subseite flexibel**.
## 2. LEDMatrix-Migration — verschoben, nicht Teil des Starts ## 2. LEDMatrix-Migration — erledigt (Phase 5)
- Keine Migration von `/ledmatrix/` zum Start. Die Seite bleibt vorerst auf stefankoelle.de. - `/ledmatrix/` wurde vollständig ins Monorepo migriert und liegt unter `stefankoelle/de/ledmatrix/`.
- Aus smarthome.moonweb.org wird lediglich **nach draußen verlinkt** (Übergangslösung). - Deploy erfolgt über IONOS SFTP alongside dem stefankoelle.de Onepager.
- Migration erfolgt in einer späteren Phase, nicht Teil von Phase 1. - Die URL `stefankoelle.de/ledmatrix/` bleibt unverändert bestehen.
- **Keine weiteren Einzelseiten-Migrationen zum Start** — bewusste Entscheidung, jetzt mit der Struktur zu beginnen statt weiter Einzelseiten zu pflegen.
## 3. Detailtiefe pro Domain — final festgelegt ## 3. Detailtiefe pro Domain — final festgelegt
+7 -6
View File
@@ -1,6 +1,6 @@
# moonweb.org — Implementation Plan # moonweb.org — Implementation Plan
Companion to `SPEC.md`. Defines order of work. All five sites (hub, infra, smarthome, code, retro) launch **simultaneously** — no staged rollout by domain. Companion to `SPEC.md`. Defines order of work. All sites (hub, infra, smarthome, code, retro, stefankoelle) launch **simultaneously** — no staged rollout by domain.
## Phase 0 — Repo & tooling setup ## Phase 0 — Repo & tooling setup
@@ -29,7 +29,7 @@ Work order within this phase is flexible since all domains launch together; sugg
- One overview page listing what hardware exists. - One overview page listing what hardware exists.
- Add "work in progress" notices for anything that isn't ready — better an honest short page than none. - Add "work in progress" notices for anything that isn't ready — better an honest short page than none.
5. **hub** — build last within this phase since it links to all the others. 5. **hub** — build last within this phase since it links to all the others.
- One-line description + link per destination (infra, smarthome, code, retro, and external links to stefankoelle.de, www.moonweb.org, 28k8.moonweb.org). - One-line description + link per destination (infra, smarthome, code, retro, stefankoelle, and external links to www.moonweb.org, 28k8.moonweb.org).
## Phase 2 — CI/CD ## Phase 2 — CI/CD
@@ -46,18 +46,19 @@ Work order within this phase is flexible since all domains launch together; sugg
## Phase 4 — Explicitly deferred (not part of this build) ## Phase 4 — Explicitly deferred (not part of this build)
- Migrating `/ledmatrix/` and any other stefankoelle.de sub-pages into smarthome.
- Deciding on 28k8.moonweb.org's future (stay separate vs. eventual monorepo inclusion). - Deciding on 28k8.moonweb.org's future (stay separate vs. eventual monorepo inclusion).
- Building any Perplexity-backchannel mechanism for reusing published site content in this project. - Building any Perplexity-backchannel mechanism for reusing published site content in this project.
- Redirecting the apex domain from `www.moonweb.org` to `hub.moonweb.org`. - Redirecting the apex domain from `www.moonweb.org` to `hub.moonweb.org`.
- Any analytics, "last updated" timestamps, or scheduled/automated content generation beyond the one-time GitHub aggregator run. - Any analytics, "last updated" timestamps, or scheduled/automated content generation beyond the one-time GitHub aggregator run.
- Porting stefankoelle.de into the monorepo — stays external.
## Definition of done for this build ## Definition of done for this build
- All five sites live on Cloudflare Pages under their intended domains. - All sites live on their respective platforms:
- hub, infra, smarthome, code, retro on Cloudflare Pages under their intended domains.
- stefankoelle.de on IONOS via SFTP deployment.
- code.moonweb.org reflects the current GitHub repos via the `.moonweb.yml` aggregator, grouped by subcategory. - code.moonweb.org reflects the current GitHub repos via the `.moonweb.yml` aggregator, grouped by subcategory.
- smarthome.moonweb.org gives an accurate picture of what's running on the homelab today, with detail pages only where content already existed. - smarthome.moonweb.org gives an accurate picture of what's running on the homelab today, with detail pages only where content already existed.
- infra.moonweb.org describes the stack shallowly with zero sensitive data leaked. - infra.moonweb.org describes the stack shallowly with zero sensitive data leaked.
- retro.moonweb.org exists with an honest, minimal overview (WIP notices allowed). - retro.moonweb.org exists with an honest, minimal overview (WIP notices allowed).
- hub.moonweb.org correctly links everything, including the untouched external sites (stefankoelle.de, www.moonweb.org, 28k8.moonweb.org). - hub.moonweb.org correctly links everything, including the external sites (www.moonweb.org, 28k8.moonweb.org).
- stefankoelle.de is a working onepager with CV, Projects, Languages, Impressum, and the LED Matrix documentation sub-page.
+49 -21
View File
@@ -8,34 +8,34 @@ infra.moonweb.org → 🏗️ Infrastructure overview (Proxmox, Synology,
smarthome.moonweb.org → 🏡 Smart home projects & dashboards smarthome.moonweb.org → 🏡 Smart home projects & dashboards
code.moonweb.org → 💻 Curated GitHub project catalog code.moonweb.org → 💻 Curated GitHub project catalog
retro.moonweb.org → 🕹️ Physical retro hardware collection retro.moonweb.org → 🕹️ Physical retro hardware collection
stefankoelle.de → 👤 CV, career, personal site (LED Matrix docs)
``` ```
> **External sites** (not in this monorepo): [stefankoelle.de](https://stefankoelle.de) (CV), [www.moonweb.org](https://www.moonweb.org) (2000s time capsule), [28k8.moonweb.org](https://28k8.moonweb.org) (90s BBS archive). > **Other sites** (not in this monorepo): [www.moonweb.org](https://www.moonweb.org) (2000s time capsule), [28k8.moonweb.org](https://28k8.moonweb.org) (90s BBS archive).
--- ---
## 📐 Architecture ## 📐 Architecture
``` ```
┌─────────────────────────────────────────────────────────┐ ┌─────────────────────────────────────────────────────────────
│ GitHub Actions CI │ │ GitHub Actions CI
│ ┌──────────┐ ┌──────────┐ ┌──────────┐ ┌────────┐ │ │ ┌──────────┐ ┌──────────┐ ┌──────────┐ ┌────────┐
│ │ build:hub │ │build:infra│ │build:smart│ │build:… │ │ │ │ build:hub │ │build:infra│ │build:smart│ │build:… │
│ └────┬─────┘ └────┬─────┘ └────┬─────┘ └───┬────┘ │ │ └────┬─────┘ └────┬─────┘ └────┬─────┘ └───┬────┘
│ │ │ │ │ │ │ │ │ │ │
│ ▼ ▼ ▼ ▼ │ │ ▼ ▼ ▼ ▼
│ dist/hub/ dist/infra/ dist/smarthome/ dist/…/ │ │ dist/hub/ dist/infra/ dist/smarthome/ dist/…/
└──────────────────────┬──────────────────────────────────┘ └──────────────────────┬────────────────────────┬──────────────┘
┌────────────┴──────────┐ ┌────────┴────────┐
┌────────────────────────┐ ▼ ▼ ▼ │
Cloudflare Workers ┌─────────────────┐ ┌──────────────┐
(Cloudflare Workers) │ Cloudflare Pages │ │ IONOS SFTP │
└────────────────────────┘ │ (5 sites) │ │ (stefankoelle│ │
└────────┬────────┘ └──────┬───────┘
┌──────────────┼──────────────┐ ▼ ▼ │
▼ ▼ ▼ hub / infra / ... stefankoelle.de │
hub.moonweb.org infra.moonweb.org …
``` ```
--- ---
@@ -90,8 +90,9 @@ npm run dev:infra # http://localhost:8082
npm run dev:smarthome # http://localhost:8083 npm run dev:smarthome # http://localhost:8083
npm run dev:code # http://localhost:8084 npm run dev:code # http://localhost:8084
npm run dev:retro # http://localhost:8085 npm run dev:retro # http://localhost:8085
npm run dev:stefankoelle # http://localhost:8086
npm run dev # all 5 in parallel npm run dev # all 6 in parallel
``` ```
Each site has its own minimal Eleventy config (`<site>/eleventy.config.js`). Live reload is built in. Each site has its own minimal Eleventy config (`<site>/eleventy.config.js`). Live reload is built in.
@@ -124,6 +125,12 @@ moonweb-site/
├── code/ # 💻 GitHub catalog ├── code/ # 💻 GitHub catalog
│ └── _data/repos.json # populated by the aggregator │ └── _data/repos.json # populated by the aggregator
├── retro/ # 🕹️ Retro hardware (WIP) ├── retro/ # 🕹️ Retro hardware (WIP)
├── stefankoelle/ # 👤 CV, career, personal site
│ ├── eleventy.config.js
│ ├── index.njk # Onepager (CV, Projects, Languages)
│ ├── cv-print.njk # CV-only for PDF generation
│ ├── ledmatrix/ # LED Matrix WebServer documentation
│ └── assets/ # CSS, JS, images, favicons
├── shared/ # 🔧 Shared components ├── shared/ # 🔧 Shared components
│ ├── _includes/ │ ├── _includes/
│ │ ├── base.njk # base layout (header, site-switcher, footer) │ │ ├── base.njk # base layout (header, site-switcher, footer)
@@ -148,6 +155,8 @@ moonweb-site/
## 🔄 CI/CD Pipeline ## 🔄 CI/CD Pipeline
### Cloudflare Pages (moonweb sites)
Defined in `.github/workflows/build-deploy.yml`: Defined in `.github/workflows/build-deploy.yml`:
``` ```
@@ -169,6 +178,25 @@ push to main
- `CLOUDFLARE_API_TOKEN` — Workers:Edit permission - `CLOUDFLARE_API_TOKEN` — Workers:Edit permission
- `CLOUDFLARE_ACCOUNT_ID` — Cloudflare account ID - `CLOUDFLARE_ACCOUNT_ID` — Cloudflare account ID
### IONOS SFTP (stefankoelle.de)
Defined in `.github/workflows/deploy-stefankoelle.yml`:
```
push to main (paths: stefankoelle/**)
├── Build stefankoelle
│ └── npm run build:stefankoelle
└── Deploy via SFTP
└── lftp mirror → IONOS /deploy/stefankoelle/
```
**Required secrets:**
- `IONOS_SFTP_HOST`
- `IONOS_SFTP_USER`
- `IONOS_SFTP_PASSWORD`
--- ---
## 🐍 GitHub Aggregator (code.moonweb.org) ## 🐍 GitHub Aggregator (code.moonweb.org)
+18 -18
View File
@@ -14,10 +14,10 @@ moonweb-site (monorepo)
├── infra/ → infra.moonweb.org System architecture / stack overview ├── infra/ → infra.moonweb.org System architecture / stack overview
├── smarthome/ → smarthome.moonweb.org What the homelab actually runs, and why ├── smarthome/ → smarthome.moonweb.org What the homelab actually runs, and why
├── code/ → code.moonweb.org Curated GitHub catalog ├── code/ → code.moonweb.org Curated GitHub catalog
── retro/ → retro.moonweb.org Physical retro hardware collection ── retro/ → retro.moonweb.org Physical retro hardware collection
└── stefankoelle/→ stefankoelle.de CV, career, personal site (SFTP deploy)
outside the monorepo, untouched: outside the monorepo, untouched:
├── stefankoelle.de CV, career, personal (extern gehostet)
├── www.moonweb.org finished, no overlap (2001-style internet time capsule) ├── www.moonweb.org finished, no overlap (2001-style internet time capsule)
├── 28k8.moonweb.org 90s BBS/scene archive, separate approach, may migrate later (undecided) ├── 28k8.moonweb.org 90s BBS/scene archive, separate approach, may migrate later (undecided)
@@ -43,7 +43,7 @@ Apex domain `moonweb.org` currently redirects to `www.moonweb.org`. This stays a
- **Overview (index) pages** use a shared card-grid layout (reference: clean card-grid layout with banner header, grouped card sections, sans-serif, generous whitespace, light theme only, no heavy JS). - **Overview (index) pages** use a shared card-grid layout (reference: clean card-grid layout with banner header, grouped card sections, sans-serif, generous whitespace, light theme only, no heavy JS).
- **Detail/sub-pages** keep the same header but may use a freer layout below it (reference: `/ledmatrix/` on stefankoelle.de today — pin tables, API docs, photos in free layout instead of a rigid card grid). - **Detail/sub-pages** keep the same header but may use a freer layout below it (reference: `/ledmatrix/` on stefankoelle.de today — pin tables, API docs, photos in free layout instead of a rigid card grid).
Note: cv (stefankoelle.de) is external and uses its own independent design — it does not follow this principle. Note: stefankoelle.de is now part of the monorepo but uses its own independent design — it does not follow this header-consistent principle.
### 4.2 Accent colors per domain ### 4.2 Accent colors per domain
@@ -57,7 +57,7 @@ Note: cv (stefankoelle.de) is external and uses its own independent design — i
### 4.3 URL convention ### 4.3 URL convention
`domain/slug/` — lowercase, hyphenated, trailing slash, matching the existing stefankoelle.de pattern (e.g. `/ledmatrix/`) so future detail pages stay consistent even if content later migrates between sites. cv (stefankoelle.de) follows its own existing URL patterns and is not part of this convention. `domain/slug/` — lowercase, hyphenated, trailing slash, matching the existing stefankoelle.de pattern (e.g. `/ledmatrix/`) so future detail pages stay consistent even if content later migrates between sites.
## 5. Content depth rules (per domain) ## 5. Content depth rules (per domain)
@@ -70,8 +70,6 @@ Note: cv (stefankoelle.de) is external and uses its own independent design — i
General rule across all domains: **if content is too thin for a good detail page, skip the detail page — don't create a placeholder.** General rule across all domains: **if content is too thin for a good detail page, skip the detail page — don't create a placeholder.**
Note: cv (stefankoelle.de) is external and not subject to these rules.
## 6. Infra content redaction rule ## 6. Infra content redaction rule
Because infra must stay shallow and public-safe: Because infra must stay shallow and public-safe:
@@ -79,11 +77,11 @@ Because infra must stay shallow and public-safe:
- **Allowed:** architecture level — Proxmox + Synology + Docker host, VLAN concept without concrete internal IP plans, which service types run, which tools are used. - **Allowed:** architecture level — Proxmox + Synology + Docker host, VLAN concept without concrete internal IP plans, which service types run, which tools are used.
- **Not allowed:** concrete IP addresses, WireGuard keys/preshared keys, passwords, internal hostnames that allow inference, backup targets with credentials. - **Not allowed:** concrete IP addresses, WireGuard keys/preshared keys, passwords, internal hostnames that allow inference, backup targets with credentials.
This rule applies to any domain but is most relevant for infra, since the source documents (e.g. Heimnetzwerk-Final-v3.2, GL_Flint2_Final_v2) currently contain real IPs and keys that must be actively stripped during migration. cv (stefankoelle.de) is maintained separately and not subject to this rule. This rule applies to any domain but is most relevant for infra, since the source documents (e.g. Heimnetzwerk-Final-v3.2, GL_Flint2_Final_v2) currently contain real IPs and keys that must be actively stripped during migration.
## 7. Language ## 7. Language
All five sites (hub, infra, smarthome, code, retro) are written **entirely in English**. Existing German source documents are translated once during migration via a single AI-assisted pass — not a recurring process. New `.moonweb.yml` metadata and generated content are authored in English from the start. cv (stefankoelle.de) remains in its existing language. All sites in the monorepo are written **entirely in English**. Existing German source documents are translated once during migration via a single AI-assisted pass — not a recurring process. New `.moonweb.yml` metadata and generated content are authored in English from the start.
## 8. GitHub automation (code.moonweb.org) ## 8. GitHub automation (code.moonweb.org)
@@ -100,16 +98,15 @@ summary: "Compact MVG/S-Bahn departure monitor with configurable stations."
repo_url: "https://github.com/skoelle/mvg-departures" repo_url: "https://github.com/skoelle/mvg-departures"
``` ```
A local aggregator script reads `.moonweb.yml` from all repos via the GitHub API, an AI pass turns the raw YAML into readable card copy, and the result is committed into `code/_data/repos.json` inside the monorepo. This runs manually, on demand — no scheduled automation for now. cv (stefankoelle.de) is not included in this automation. A local aggregator script reads `.moonweb.yml` from all repos via the GitHub API, an AI pass turns the raw YAML into readable card copy, and the result is committed into `code/_data/repos.json` inside the monorepo. This runs manually, on demand — no scheduled automation for now.
## 9. Content maintenance ## 9. Content maintenance
- infra, smarthome, retro: **fully manual**, edited in vim, committed via git push. No automation. - infra, smarthome, retro, stefankoelle: **fully manual**, edited in vim, committed via git push. No automation.
- code: the only automated piece is the GitHub aggregator described in §8. - code: the only automated piece is the GitHub aggregator described in §8.
- No "last updated" timestamps are shown anywhere — the goal is that content is simply kept current, not that staleness is displayed. - No "last updated" timestamps are shown anywhere — the goal is that content is simply kept current, not that staleness is displayed.
- No analytics/tracking of any kind on any of the five sites. - No analytics/tracking of any kind on any site.
- Images/assets live versioned directly in the monorepo (no external asset host). - Images/assets live versioned directly in the monorepo (no external asset host).
- cv (stefankoelle.de): maintained separately, linked from hub/site-switcher.
## 10. Repository structure ## 10. Repository structure
@@ -121,6 +118,12 @@ moonweb-site/
├── code/ ├── code/
│ └── _data/repos.json # populated by the GitHub aggregator │ └── _data/repos.json # populated by the GitHub aggregator
├── retro/ ├── retro/
├── stefankoelle/ # CV, career, personal site
│ ├── eleventy.config.js
│ ├── index.njk # Onepager (CV, Projects, Languages)
│ ├── cv-print.njk # CV-only for PDF generation
│ ├── ledmatrix/ # LED Matrix WebServer documentation
│ └── assets/ # CSS, JS, images, favicons
├── shared/ ├── shared/
│ ├── _includes/ │ ├── _includes/
│ │ ├── base.njk # shared header + footer layout │ │ ├── base.njk # shared header + footer layout
@@ -134,25 +137,22 @@ moonweb-site/
├── PLAN.md # how and in what order ├── PLAN.md # how and in what order
├── TODO.md # open items and workflow ├── TODO.md # open items and workflow
└── .github/workflows/ └── .github/workflows/
── build-deploy.yml # builds all sites, deploys each to its Cloudflare Pages project ── build-deploy.yml # builds all sites, deploys to Cloudflare Pages
└── deploy-stefankoelle.yml # builds stefankoelle, deploys via IONOS SFTP
``` ```
Note: `cv/` (stefankoelle.de) is hosted externally and linked from hub/site-switcher — it is not part of this monorepo.
## 11. Technical stack ## 11. Technical stack
- **Static site generator:** Eleventy (11ty) — markdown/YAML-first, minimal JS, `_data` folders map directly onto the `.moonweb.yml` aggregator output, low maintenance for five sites at this scale. - **Static site generator:** Eleventy (11ty) — markdown/YAML-first, minimal JS, `_data` folders map directly onto the `.moonweb.yml` aggregator output, low maintenance for five sites at this scale.
- **Build:** entirely in GitHub Actions. - **Build:** entirely in GitHub Actions.
- **Deploy:** Cloudflare Pages — five separate Pages projects (one per public domain: hub, infra, smarthome, code, retro), since Cloudflare Pages binds one custom-domain set per project. One shared GitHub Actions workflow builds all five sites and deploys each output folder to its respective Pages project. - **Deploy:** Cloudflare Pages — five separate Pages projects (one per public domain: hub, infra, smarthome, code, retro), since Cloudflare Pages binds one custom-domain set per project. stefankoelle.de deploys via IONOS SFTP. Two GitHub Actions workflows handle deployment.
- **Runtime:** fully static, no server-side code, no containers for the website itself (distinct from the actual homelab services running on the Docker host). - **Runtime:** fully static, no server-side code, no containers for the website itself (distinct from the actual homelab services running on the Docker host).
- **DNS:** already on Cloudflare — no additional setup step needed for Pages custom domains. - **DNS:** already on Cloudflare — no additional setup step needed for Pages custom domains.
- **Local preview:** Eleventy's built-in dev server with live reload, run per-site (`npm run dev:<site>`) before any commit. - **Local preview:** Eleventy's built-in dev server with live reload, run per-site (`npm run dev:<site>`) before any commit.
## 12. Explicitly out of scope for this build ## 12. Explicitly out of scope for this build
- Migrating `/ledmatrix/` (and any other existing stefankoelle.de sub-pages) into smarthome — stays linked externally for now, migrates in a later phase.
- Migrating 28k8.moonweb.org into the monorepo — undecided, revisit later, likely never. - Migrating 28k8.moonweb.org into the monorepo — undecided, revisit later, likely never.
- Any Perplexity-backchannel mechanism (website content reusable inside this project) — deferred, no time invested now. - Any Perplexity-backchannel mechanism (website content reusable inside this project) — deferred, no time invested now.
- Analytics of any kind. - Analytics of any kind.
- Automated content generation/translation pipelines beyond the one-time GitHub aggregator for code and the one-time translation pass during migration. - Automated content generation/translation pipelines beyond the one-time GitHub aggregator for code and the one-time translation pass during migration.
- Porting stefankoelle.de into the monorepo — stays external.
+3 -2
View File
@@ -398,8 +398,9 @@ footer {
} }
.nav-menu { .nav-menu {
flex-direction: column; flex-wrap: wrap;
gap: 1rem; justify-content: center;
gap: 0.75rem 1.25rem;
} }
main { main {