ccn/README.md

# 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. |
| **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:

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).
   The manifest's `name` / `short_name` are empty and are not rewritten by bootstrap.
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`.