jeanlucmakiola.de/PLANNING.md

jeanlucmakiola.de — personal website

Status: discussion / not started · Started 2026-06-28

Goal

A simple personal website (with room to grow into a blog), self-hosted on Coolify, privacy-respecting analytics, solid SEO, and an AI-driven authoring flow (content written as files by an agent, reviewed via git diff, auto-deployed on push).

Hard requirements

• Self-hosted deploy on Coolify (own infra)
• Privacy-respecting analytics (Umami preferred)
• SEO: sitemap, RSS, canonical URLs, Open Graph, fast/static
• AI-driven flow: agent can author/edit content via CLI/files (and/or API)
• Keep it simple; nothing crazy. Blog is a likely-but-later addition.

Recommended stack (proposed)

Concern	Choice	Why
Framework	Astro (static output)	Content-first, zero-JS default, content collections, great SEO
Content	Markdown/MDX in git (src/content/)	AI writes files; git is the API; no lock-in
Analytics	Umami, self-hosted on Coolify	Privacy-respecting, cookieless, one <script> tag
SEO	@astrojs/sitemap + @astrojs/rss + OG	Mostly batteries-included
Deploy	Coolify static site (Docker/Nixpacks → dist/, served by Caddy/nginx)	Auto-deploy on git push
Design	TBD — align with Floret/M3 leanings later	per design-workflow rule, consult ui-ux-pro-max before building UI

AI authoring loop

1. Agent writes/edits src/content/blog/<slug>.md (frontmatter: title, date, description, tags)
2. User reviews git diff
3. Commit + push → Coolify rebuilds → live

Decisions (locked 2026-06-28)

• Framework: Astro (static)
• Content authoring: Markdown-in-git
• Analytics: Umami, self-hosted on Coolify
• Domain confirmed: jeanlucmakiola.de
• Scope of v1: homepage only, or homepage + blog from the start

Build plan (v1)

1. Scaffold Astro project (hand-rolled, Astro 7, strict TS)
2. Base layout + SEO head (title/description/canonical/OG), global styles (neutral)
3. Homepage (intro + latest posts)
4. Blog: content collection + index page + post template + tag pages
5. @astrojs/sitemap + RSS feed + robots.txt
6. Umami script in base layout (env-gated so it's off in dev)
7. Dockerfile (build → static, served by Caddy) + Caddyfile
8. Visual design pass — M3 Expressive, brand-faithful (see below)
9. Add og-default.png (1200×630) to public/
10. Umami already running on Coolify (service umami.jeanlucmakiola.de)
11. Deployed site on Coolify (Dockerfile build); PUBLIC_UMAMI_SRC set
12. DNS + HTTPS live — https://jeanlucmakiola.de serves 200

Deployment (live 2026-06-28)

• Live: https://jeanlucmakiola.de (Coolify, server localhost, project Websites/production)
• Repo: gitea.jeanlucmakiola.de/makiolaj/jeanlucmakiola.de (branch main, public)
• Coolify app uuid: q144cv08qb5gakw7fez37ys7; build-pack dockerfile, port 80
• Build: npm install (not npm ci) on node:22-slim — Astro 7's wasm32 optional deps (@emnapi/*) break npm ci's strict lock-sync across npm versions.
• Analytics: ON — PUBLIC_UMAMI_SRC + PUBLIC_UMAMI_WEBSITE (625eb309-1d8d-4c79-9048-66862d2045ce) set as build-time vars.
• Healthcheck: enabled (GET / → 200); app reports running:healthy.
• OG image: public/og-default.png (1200×630, brand) generated from assets.

Design system (M3 Expressive)

• Tokens in src/styles/tokens.css as --md-sys-* CSS custom properties (color roles, type scale, shape, elevation, motion, 8dp spacing); light + dark.
• Brand = red + monochrome. #FF4242 is an ACCENT only (logo dot, name period, eyebrow tick, active-nav underline, one filled button, card arrows, links). Surfaces are NEUTRAL gray — earlier red-tinted/red-bar version was rejected as "too red heavy".
• The pine-silhouette asset is grayscale (not green) — confirmed; no green hue. tertiary role is a warm neutral, not a color.
• Fonts: Inter + JetBrains Mono, self-hosted via Fontsource (no Google CDN).
• Homepage is a clean portfolio: hero → About → Selected work cards → Latest writing rows.
• Favicon = the rounded red "JM." mark; header is a typographic JLM. logotype.
• Projects are a content collection (src/content/projects/*.md, schema in content.config.ts): frontmatter (name, order, status, released, platform, summary, links{gitea,fdroid,donate,translate}) + Markdown body. Single source of truth for both the homepage cards and /work.
• /work index lists all apps; /work/<slug> is a per-app page with its own link set (F-Droid/Gitea/Donate/Translate, shown only when present) + overview. Currently: Calendula (released), Agendula (in dev), floret-kit (design system).

Verified

• npm install + npm run build succeed; 4 pages + RSS + sitemap generated.
• Astro 7.0.3, 0 npm audit vulnerabilities (2026-06-28).
• Screenshotted home/blog/post desktop + mobile (DARK mode). Light mode not yet visually verified — headless couldn't force the scheme — but tokens are standard M3.

Notes

• Coolify supports git-push auto-deploy; Umami has an official Docker image deployable as its own Coolify service.