From a9dda1e2a57f559469243cdbc99cc080d934cebf Mon Sep 17 00:00:00 2001 From: Stefan Koelle Date: Fri, 14 Aug 2026 13:48:32 +0200 Subject: [PATCH] documentation update --- DESIGN.md | 9 ++-- PLAN.md | 13 ++--- README.md | 70 +++++++++++++++++-------- SPEC.md | 36 ++++++------- stefankoelle/ledmatrix/assets/style.css | 5 +- 5 files changed, 81 insertions(+), 52 deletions(-) diff --git a/DESIGN.md b/DESIGN.md index 66887e8..9ebe48a 100755 --- a/DESIGN.md +++ b/DESIGN.md @@ -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**. -## 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. -- Aus smarthome.moonweb.org wird lediglich **nach draußen verlinkt** (Übergangslösung). -- Migration erfolgt in einer späteren Phase, nicht Teil von Phase 1. -- **Keine weiteren Einzelseiten-Migrationen zum Start** — bewusste Entscheidung, jetzt mit der Struktur zu beginnen statt weiter Einzelseiten zu pflegen. +- `/ledmatrix/` wurde vollständig ins Monorepo migriert und liegt unter `stefankoelle/de/ledmatrix/`. +- Deploy erfolgt über IONOS SFTP alongside dem stefankoelle.de Onepager. +- Die URL `stefankoelle.de/ledmatrix/` bleibt unverändert bestehen. ## 3. Detailtiefe pro Domain — final festgelegt diff --git a/PLAN.md b/PLAN.md index 959f2f8..41d248b 100755 --- a/PLAN.md +++ b/PLAN.md @@ -1,6 +1,6 @@ # 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 @@ -29,7 +29,7 @@ Work order within this phase is flexible since all domains launch together; sugg - 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. 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 @@ -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) -- Migrating `/ledmatrix/` and any other stefankoelle.de sub-pages into smarthome. - 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. - 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. -- Porting stefankoelle.de into the monorepo — stays external. ## 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. - 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. - 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. diff --git a/README.md b/README.md index 8ae4489..0df45f1 100755 --- a/README.md +++ b/README.md @@ -8,34 +8,34 @@ infra.moonweb.org → 🏗️ Infrastructure overview (Proxmox, Synology, smarthome.moonweb.org → 🏡 Smart home projects & dashboards code.moonweb.org → 💻 Curated GitHub project catalog 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 ``` -┌─────────────────────────────────────────────────────────┐ -│ GitHub Actions CI │ -│ ┌──────────┐ ┌──────────┐ ┌──────────┐ ┌────────┐ │ -│ │ build:hub │ │build:infra│ │build:smart│ │build:… │ │ -│ └────┬─────┘ └────┬─────┘ └────┬─────┘ └───┬────┘ │ -│ │ │ │ │ │ -│ ▼ ▼ ▼ ▼ │ -│ dist/hub/ dist/infra/ dist/smarthome/ dist/…/ │ -└──────────────────────┬──────────────────────────────────┘ - │ - ▼ - ┌────────────────────────┐ - │ Cloudflare Workers │ - │ (Cloudflare Workers) │ - └────────────────────────┘ - │ - ┌──────────────┼──────────────┐ - ▼ ▼ ▼ - hub.moonweb.org infra.moonweb.org … +┌─────────────────────────────────────────────────────────────┐ +│ GitHub Actions CI │ +│ ┌──────────┐ ┌──────────┐ ┌──────────┐ ┌────────┐ │ +│ │ build:hub │ │build:infra│ │build:smart│ │build:… │ │ +│ └────┬─────┘ └────┬─────┘ └────┬─────┘ └───┬────┘ │ +│ │ │ │ │ │ +│ ▼ ▼ ▼ ▼ │ +│ dist/hub/ dist/infra/ dist/smarthome/ dist/…/ │ +└──────────────────────┬────────────────────────┬──────────────┘ + │ │ + ┌────────────┴──────────┐ ┌────────┴────────┐ + ▼ ▼ ▼ │ + ┌─────────────────┐ ┌──────────────┐ │ + │ Cloudflare Pages │ │ IONOS SFTP │ │ + │ (5 sites) │ │ (stefankoelle│ │ + └────────┬────────┘ └──────┬───────┘ │ + ▼ ▼ │ + hub / infra / ... stefankoelle.de │ ``` --- @@ -90,8 +90,9 @@ npm run dev:infra # http://localhost:8082 npm run dev:smarthome # http://localhost:8083 npm run dev:code # http://localhost:8084 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 (`/eleventy.config.js`). Live reload is built in. @@ -124,6 +125,12 @@ moonweb-site/ ├── code/ # 💻 GitHub catalog │ └── _data/repos.json # populated by the aggregator ├── 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 │ ├── _includes/ │ │ ├── base.njk # base layout (header, site-switcher, footer) @@ -148,6 +155,8 @@ moonweb-site/ ## 🔄 CI/CD Pipeline +### Cloudflare Pages (moonweb sites) + Defined in `.github/workflows/build-deploy.yml`: ``` @@ -169,6 +178,25 @@ push to main - `CLOUDFLARE_API_TOKEN` — Workers:Edit permission - `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) diff --git a/SPEC.md b/SPEC.md index c33373d..3355512 100755 --- a/SPEC.md +++ b/SPEC.md @@ -14,10 +14,10 @@ moonweb-site (monorepo) ├── infra/ → infra.moonweb.org System architecture / stack overview ├── smarthome/ → smarthome.moonweb.org What the homelab actually runs, and why ├── 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: -├── stefankoelle.de CV, career, personal (extern gehostet) ├── www.moonweb.org finished, no overlap (2001-style internet time capsule) ├── 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). - **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 @@ -57,7 +57,7 @@ Note: cv (stefankoelle.de) is external and uses its own independent design — i ### 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) @@ -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.** -Note: cv (stefankoelle.de) is external and not subject to these rules. - ## 6. Infra content redaction rule 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. - **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 -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) @@ -100,16 +98,15 @@ summary: "Compact MVG/S-Bahn departure monitor with configurable stations." 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 -- 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. - 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). -- cv (stefankoelle.de): maintained separately, linked from hub/site-switcher. ## 10. Repository structure @@ -121,6 +118,12 @@ moonweb-site/ ├── code/ │ └── _data/repos.json # populated by the GitHub aggregator ├── 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/ │ ├── _includes/ │ │ ├── base.njk # shared header + footer layout @@ -134,25 +137,22 @@ moonweb-site/ ├── PLAN.md # how and in what order ├── TODO.md # open items and workflow └── .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 - **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. -- **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). - **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:`) before any commit. ## 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. - Any Perplexity-backchannel mechanism (website content reusable inside this project) — deferred, no time invested now. - 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. -- Porting stefankoelle.de into the monorepo — stays external. diff --git a/stefankoelle/ledmatrix/assets/style.css b/stefankoelle/ledmatrix/assets/style.css index e277d63..206f8e3 100644 --- a/stefankoelle/ledmatrix/assets/style.css +++ b/stefankoelle/ledmatrix/assets/style.css @@ -398,8 +398,9 @@ footer { } .nav-menu { - flex-direction: column; - gap: 1rem; + flex-wrap: wrap; + justify-content: center; + gap: 0.75rem 1.25rem; } main {