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:

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.
Canonical site URL (scheme + host)	`https://loud.amsterdam`	The `Sitemap:` reference in `robots.txt` and the `<loc>` entry in `sitemap.xml`.

The canonical URL defaults to the reserved placeholder https://site.example.com; leaving it there is allowed (the script warns), so you can bootstrap before the domain is decided and set it later in the two crawler files.

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:

Copy & localization — Services/Website/Sources/Library/Catalogs/Localizable.xcstrings and the landing / 404 pages under Services/Website/Sources/Library.
Static assets — Services/Website/Resources/Static (CSS, JS, favicon, icons). The manifest's name / short_name are empty and are not rewritten by bootstrap.
Secrets — set a real DATABASE_PASSWORD in a git-ignored Services/Website/.env (the committed .env.local is an example only).
Domain models — the Persistence package ships a sample ExampleRecord / ExampleRepository; replace it when you add real data.

4. Build & run

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.

4.0 KiB Raw Blame History