Converted the website service project into a reusable template.

2026-07-11 16:20:33 +02:00
parent a4906f8f26
commit 4a8413359f
12 changed files with 296 additions and 38 deletions
@@ -0,0 +1,86 @@
+# Website Template
+
+This repository is a **template** for the platform's websites. It ships as a
+complete, buildable reference site whose identity is the neutral placeholder
+**`Site`** / **`site`**. You generate a real site from it in two steps:
+generate a fresh repository, then run the bootstrap script to stamp in your
+site's name and slug.
+
+## What's in here
+
+| Path | Role |
+| --- | --- |
+| `Services/Website` | The Hummingbird website service (the engine + placeholder content). |
+| `Packages/Localization`, `Packages/Persistence` | Reusable packages, **vendored** into every site — each generated repo owns its own copy. |
+| `Site.xcodeproj` | The umbrella Xcode project (renamed to your site by bootstrap). |
+| `Scripts/bootstrap` | The generator. Rewrites placeholders, then deletes itself. |
+
+The engine is intentionally copied into each site rather than shared as a
+remote dependency: a generated site is fully self-contained and can diverge
+freely. Engine fixes are propagated to existing sites by hand (or by
+re-generating and porting content).
+
+## Generating a new site
+
+### 1. Create a repository from this template
+
+On Gitea, mark this repository as a template once (repository **Settings →
+Template → “Template” checkbox**). New sites are then created with the
+**“Use this template”** button, which produces a fresh repository with its own
+history — no template commits carried over.
+
+> No Gitea button? Just clone this repo, `rm -rf .git`, and continue — the
+> bootstrap script offers to re-initialise git for you.
+
+### 2. Bootstrap
+
+Clone the new repository, then from its root run:
+
+```sh
+make bootstrap        # or: ./Scripts/bootstrap
+```
+
+You'll be asked for:
+
+| Prompt | Example | Rewrites |
+| --- | --- | --- |
+| **Site display name** (PascalCase) | `Loud` | Server name (`LoudWebsite`), `Loud.xcodeproj`, README title. |
+| **Project slug** (lowercase) | `loud-ams` | Container owner, database name/user, Compose project name. |
+
+The script rewrites the placeholder occurrences in place, renames
+`Site.xcodeproj`, optionally starts a fresh git history, and then removes
+itself along with this file and the root `Makefile`.
+
+### 3. Fill in the content
+
+Bootstrap leaves reminders, but in short:
+
+1. **Copy & localization** — `Services/Website/Sources/Library/Catalogs/Localizable.xcstrings`
+   and the landing / 404 pages under `Services/Website/Sources/Library`.
+2. **Static assets** — `Services/Website/Resources/Static` (CSS, JS, favicon, icons, manifest).
+3. **Secrets** — set a real `DATABASE_PASSWORD` in a git-ignored
+   `Services/Website/.env` (the committed `.env.local` is an example only).
+4. **Domain models** — the `Persistence` package ships a sample
+   `ExampleRecord` / `ExampleRepository`; replace it when you add real data.
+
+### 4. Build & run
+
+```sh
+cd Services/Website
+make site-run          # watch + rebuild
+# or
+make site-mount        # docker compose up --build
+```
+
+## What bootstrap does NOT change
+
+- Organisation (`Röck+Cöde VoF`) and Xcode `DEVELOPMENT_TEAM` — shared across all sites.
+- The package architecture, middleware, security headers, and persistence layer.
+- The generic `website` image name and `Makefile` command names (`site-run`, `site-mount`, …).
+
+## Maintaining the template itself
+
+Edit and test the reference site directly — it builds and its tests pass with
+the `Site` / `site` placeholders in place. Keep the placeholders intact so the
+bootstrap script's targeted replacements keep matching; if you introduce a new
+site-specific value, add a matching rewrite line in `Scripts/bootstrap`.