Přeskočit obsah

Online dokumentace (Cloudflare)

Tahle dokumentace běží i online, mimo dům, aby byla dostupná i když dům nejede (výpadek proudu, sítě, serverů). Je schovaná za přihlášením, takže se k ní dostane jen rodina a případný helper.

  • Veřejná adresa: https://docs.marada.name
  • Kde běží: Cloudflare Pages (mimo dům) — nezávislé na domácí infrastruktuře.
  • Přihlášení: Cloudflare Access — Google účet nebo kód do e-mailu.
  • Co v online verzi NENÍ: složka Osobní (smlouvy, účty, inventář majetku). Ta je jen v domácí plné verzi (viz níže).

Jak se k dokumentaci přihlásit

  1. Otevři docs.marada.name.
  2. Objeví se přihlašovací obrazovka Cloudflare Access. Dvě možnosti:
  3. Sign in with Google — jedním klikem přes svůj Google účet (rodina).
  4. Kód do e-mailu — zadáš e-mail, přijde 6místný kód, ten opíšeš.
  5. Přihlášení platí dlouho (řádově týdny), takže se to při běžném používání neptá pořád dokola.

Přístup má jen ten, jehož e-mail je na seznamu (allowlist). Aktuálně: jana.marada@gmail.com, tomas.marada@gmail.com.

Jak přidat nebo odebrat člověka

Přístup se řídí v Cloudflare (nic se necommituje do repa — e-maily nejsou v Gitu):

  1. Přihlas se do Cloudflare dashboardu → Zero Trust → Access → Applications.
  2. Otevři aplikaci docs.marada.name → záložka Policies.
  3. V pravidle Include → Emails přidej/odeber e-mailovou adresu → Save.

Odebráním e-mailu ztratí ten člověk přístup okamžitě. Žádné sdílené heslo se nemění, nic se nemusí nikomu přeposílat.

Jak to funguje (pro údržbu)

Zdroj dokumentace je tenhle repozitář. Publikace je automatická:

  1. Push na větev master na GitHubu.
  2. Cloudflare Pages si repo stáhne a sám postaví web (mkdocs build).
  3. Za pár minut je nová verze online.

Online verze se odvozuje z hlavního mkdocs.yml skriptem scripts/gen_online_mkdocs.py, který:

  • vyhodí z menu sekci Osobní, a
  • úplně vynechá složku osobni/ z buildu (není dostupná ani přes přímou adresu).

Vzniklý mkdocs.online.yml je build artefakt — negeneruje se ručně a necommituje se (je v .gitignore). Generuje ho CI i Cloudflare Pages. Díky tomu online verze nikdy „nezešediví" oproti hlavnímu mkdocs.yml — přidáš-li stránku do hlavního menu, objeví se online automaticky (kromě osobni/).

Nastavení Cloudflare Pages

Pokud by se projekt zakládal znovu (dashboard → Workers & Pages → Create → Pages → Connect to Git → repo docek/ha-config):

Položka Hodnota
Production branch master
Build command python scripts/gen_online_mkdocs.py && mkdocs build -f mkdocs.online.yml -d site
Build output directory site
Root directory /
Env var PYTHON_VERSION nenastavovat (viz níže)

Python verze: záměrně se nepinuje. Build je na verzi lhostejný (jede na čemkoli 3.9+), takže se nechává default build image Cloudflare (aktuálně 3.12–3.13, udržovaný a ne-EOL). Pin by u málo dotýkaného repa jen tiše zestárl a jednou build shodil. Kdyby někdy konkrétní verze byla přesto potřeba, nastaví se env var PYTHON_VERSION (např. 3.13).

Build deps jsou v kořenovém requirements.txt (Cloudflare nepoužívá uv). Soubor se musí jmenovat přesně requirements.txt — Cloudflare ho auto-detekuje a nainstaluje z něj; jinak by kvůli pyproject.toml spustil pip install ., které na tomhle repu (není to balík) selže. Proto build command už pip install neobsahuje — závislosti nainstaluje Cloudflare sám. Custom doména docs.marada.name se přidá v Pages → Custom domains; DNS zóna marada.name už na Cloudflare je, takže záznam se vytvoří sám (pár kliků).

Nastavení přihlášení (Cloudflare Access)

Jednorázově, v Zero Trust → Access:

  • Identity providers: Google (přes OAuth klienta z Google Cloud Console — Client ID + Secret) a One-time PIN (kód do e-mailu, bez konfigurace).
  • Application: typ Self-hosted, doména docs.marada.name.
  • Policy: Include → Emails = konkrétní allowlist (viz výše). Access je deny by default — kdo není na seznamu, nedostane se dovnitř. OTP se musí párovat se seznamem e-mailů, jinak by kód dostal kdokoli.

Domácí plná verze (s Osobním) — plánováno, zatím není

Cíl: doma na lokální síti mít plnou verzi včetně složky Osobní, venku jen oříznutou. Skript gen_online_mkdocs.py staví online (oříznutou) variantu; domácí plná verze je prostě standardní mkdocs build z hlavního mkdocs.yml.

Otevřené k dořešení (proto zatím nenasazeno):

  • Kde ji hostovat — na kterém domácím stroji (běžící web s plným buildem).
  • TLS certifikát — pokud by měla běžet na stejné adrese docs.marada.name přes lokální DNS override (split-horizon), potřebuje platný cert pro tu doménu i lokálně, jinak prohlížeč hlásí varování. Čistší je dát domácí verzi vlastní adresu (např. docs.dum.marada.name) a split-horizon neřešit.

Detaily a rozhodnutí viz docs/todos.md a docs/decision_log.md.

Co dělat, když to nefunguje

  • Nová změna se online neobjevila → zkontroluj, že prošel push na master a že build v Cloudflare Pages (dashboard → projekt → Deployments) skončil zeleně. Červený build → rozklikni log; nejčastěji chybí závislost v requirements-docs.txt nebo je chyba v Markdownu (build je --strict).
  • Build padá na gen_online_mkdocs.py → nejspíš se v mkdocs.yml přejmenovala/smazala sekce Osobní. Skript to schválně shodí (fail fast), aby omylem nepublikoval osobní věci. Uprav skript nebo název sekce.
  • Nejde se přihlásit → e-mail není na allowlistu (viz Jak přidat člověka), nebo se přihlašuješ jiným Google účtem, než který je na seznamu.
  • Dům nejede, ale dokumentace ano → tak to má být. Online verze běží na Cloudflare, nezávisle na domě. Přihlásíš se přes mobil (LTE) i při výpadku.