feat(docs): update

[athulrajtflycatchtech]

Changes

• update onboarding and deployment instructions; enhance quick start guide with detailed steps for Docker Compose, clarify staff user provisioning, and add new seed data structure for improved setup experience.

Reviewer

@athulrajtflycatchtech

[qodo-code-review]

PR Summary by Qodo

Fix clean frontend builds and expand Docker onboarding

🐞 Bug fix ✨ Enhancement 📝 Documentation ⚙️ Configuration changes 🕐 20-40 Minutes

AI Description

• Adds a deterministic seed snapshot for clean Frontend builds and checks.
• Seeds matching About-page content through the Backend CLI.
• Clarifies Docker Compose startup, migrations, staff bootstrap, and credential handling.

Diagram

graph TD
  Onboarding["Setup Guides"] --> Compose["Docker Compose"] --> BackendCLI["Backend Seed CLI"] --> Records[("Managed Records")]
  FrontendBuild["Frontend Scripts"] --> Guard["Snapshot Guard"] --> Snapshot["Published Snapshot"] --> Astro["Astro Build"]
  Seed["Seed Snapshot"] --> Guard

Loading

High-Level Assessment

The following are alternative approaches to this PR:

1. Commit the generated published snapshot

• ➕ Removes the pre-build copy script.
• ➕ Makes every checkout contain the exact build input.
• ➖ Tracks a mutable export artifact and creates frequent content churn.
• ➖ Risks committing environment-specific or stale published data.

2. Export content during the Docker build

• ➕ Builds directly from Backend-managed published content.
• ➕ Avoids maintaining parallel Backend and Frontend seed definitions.
• ➖ Couples image builds to a running Backend, database, and credentials.
• ➖ Reduces build reproducibility and complicates local and CI environments.

Recommendation: Keep the checked-in seed plus existence guard. It preserves exported snapshots when present while making clean and offline builds deterministic; a future improvement could generate both seed representations from one canonical fixture to prevent drift.

Files changed (11) +189 / -33

Enhancement (2) +73 / -0

seed_records.pySeed the placeholder About page +19/-0

Seed the placeholder About page

• Adds repeatable About-page content and includes it in the managed-record seeding loop, aligning Backend seed data with the Frontend fallback snapshot.

apps/Backend/src/flycatch_api/cli/seed_records.py

published.seed.jsonProvide deterministic seed content for Frontend builds +54/-0

Provide deterministic seed content for Frontend builds

• Adds a checked-in publication snapshot containing local site settings and Home and About page content for clean or offline builds.

apps/Frontend/src/data/published.seed.json

Bug fix (2) +22 / -2

package.jsonEnsure snapshot availability before build and check +2/-2

Ensure snapshot availability before build and check

• Runs the snapshot guard before both Astro build and Astro check, allowing clean checkouts and container builds to proceed without a generated publication export.

apps/Frontend/package.json

ensure-published-snapshot.mjsAdd a clean-build snapshot fallback +20/-0

Add a clean-build snapshot fallback

• Preserves an existing published snapshot or copies the checked-in seed into place when absent. It fails clearly if neither source exists.

apps/Frontend/scripts/ensure-published-snapshot.mjs

Documentation (6) +85 / -31

.gitignoreClarify the ignored snapshot’s seed source +1/-1

Clarify the ignored snapshot’s seed source

• Updates the comment to distinguish the ignored generated publication snapshot from the checked-in seed snapshot.

.gitignore

README.mdExpand the Docker Compose quick-start workflow +44/-16

Expand the Docker Compose quick-start workflow

• Documents environment setup, image builds, migrations, record seeding, staff bootstrap, login, rebuilds, and safe shutdown. It also clarifies that Compose provides neither migrations nor default credentials.

README.md

README.mdDocument complete deployment startup commands +20/-1

Document complete deployment startup commands

• Adds build, migration, seeding, and staff-bootstrap commands for both deployment-directory and repository-root usage. It clarifies password prompting and links to detailed onboarding guidance.

deployment/README.md

onboarding.mdClarify staff provisioning and local startup +13/-6

Clarify staff provisioning and local startup

• Explains Compose limitations, secret handling, staff roles, password behavior, idempotency, and containerized provisioning commands. It also distinguishes example accounts from test fixtures.

docs/onboarding.md

quickstart.mdAlign foundation setup with the Compose workflow +3/-3

Align foundation setup with the Compose workflow

• Updates startup instructions to build images, seed records, bootstrap two staff users, and explicitly note the absence of default credentials.

specs/001-website-foundation/quickstart.md

quickstart.mdClarify containerized RBAC bootstrap steps +4/-4

Clarify containerized RBAC bootstrap steps

• Documents rebuilt service startup, the Compose execution prefix for bootstrap, example-only emails, minimum password length, and idempotent reruns.

specs/002-auth-rbac/quickstart.md

Other (1) +9 / -0

.dockerignoreExclude local artifacts and secrets from Frontend builds +9/-0

Exclude local artifacts and secrets from Frontend builds

• Prevents dependencies, build outputs, reports, Git metadata, and environment files from entering the Frontend Docker build context.

apps/Frontend/.dockerignore

[qodo-code-review]

Code Review by Qodo

🐞 Bugs (3) 📘 Rule violations (0) 📜 Skill insights (0)

1. Gateway port breaks admin API 🐞 Bug ≡ Correctness

Description

Changing the documented GATEWAY_PORT only changes the host port, while the Administration FE image
compiles its API origin as http://localhost:8080. Opening /admin on the configured port
therefore still sends authentication and API requests to port 8080, where the gateway may not be
listening.

Code

README.md[98]

+Gateway (default `http://localhost:8080`, `GATEWAY_PORT` in `.env`):

Evidence

Compose maps GATEWAY_PORT to the gateway's container port but supplies PUBLIC_ORIGIN only as a
runtime environment variable. The Administration FE Dockerfile instead hardcodes
PUBLIC_ORIGIN=http://localhost:8080 before its static build, and admin-api.ts derives every API
request from that compiled value.

deployment/docker-compose.yml[61-74]
apps/Administration-FE/Dockerfile[1-15]
apps/Administration-FE/src/lib/admin-api.ts[29-31]
deployment/.env.example[3-5]

Agent prompt

The issue below was found during a code review. Follow the provided context and guidance below and implement a solution

## Issue description
The documentation advertises `GATEWAY_PORT` customization, but the Administration FE image hardcodes port 8080 into its compiled API origin. Make the configured public origin available during the image build or document and enforce the required matching configuration.

## Issue Context
Astro embeds `PUBLIC_ORIGIN` at build time. A runtime Compose environment value cannot modify the already-built static bundle.

## Fix Focus Areas
- README.md[98-104]
- deployment/docker-compose.yml[61-74]
- apps/Administration-FE/Dockerfile[1-9]
- deployment/.env.example[3-5]

ⓘ Copy this prompt and use it to remediate the issue with your preferred AI generation tools

---

2. Provision command misses container 🐞 Bug ≡ Correctness

Description

The Docker Compose quick start tells users to run flycatch-provision-admin directly on the host,
although this workflow installs the executable only inside the backend image. Users following these
instructions receive a command-not-found error unless they separately install the backend package.

Code

README.md[88]

+4. Sign in at `http://localhost:8080/admin`. Later staff: `flycatch-provision-admin --email someone@example.com --role editor` (`--role` is required: `administrator` or `editor`).

Evidence

The executable is defined by the Backend Python package and copied into /usr/local/bin in the
backend image. The Compose quick start runs all preceding Backend CLIs through `docker compose ...
exec backend`, and onboarding uses that same required prefix for provisioning.

apps/Backend/pyproject.toml[31-34]
apps/Backend/Dockerfile[6-13]
README.md[73-88]
docs/onboarding.md[27-27]

Agent prompt

The issue below was found during a code review. Follow the provided context and guidance below and implement a solution

## Issue description
The Docker Compose quick start presents the later-staff provisioning executable as a host command, but the setup does not install the Backend package on the host. Prefix it with the same Compose `exec backend` command used for the other Backend CLIs.

## Issue Context
The onboarding document already demonstrates the container-qualified form, and the executable is installed by the Backend image from its Python package entry point.

## Fix Focus Areas
- README.md[88-88]
- docs/onboarding.md[27-27]

ⓘ Copy this prompt and use it to remediate the issue with your preferred AI generation tools

---

3. Compose already applies migrations 🐞 Bug ☼ Reliability

Description

The new instructions claim Compose does not apply migrations and direct users to execute Alembic
after startup, but the backend container already runs alembic upgrade head as its startup command.
On first boot, executing the documented command while the container startup migration is still
running can launch two migrations against the same database and fail on conflicting schema changes.

Code

deployment/README.md[R28-32]

+Compose does not provision staff. After services are healthy:
+
+```bash
+docker compose exec backend alembic upgrade head
+docker compose exec backend flycatch-seed-records

Evidence

The backend Dockerfile's active CMD runs Alembic before Uvicorn, and the Compose backend service
does not override that command. The added deployment instructions nevertheless tell users to execute
Alembic again immediately after bringing up the same container.

apps/Backend/Dockerfile[11-18]
deployment/docker-compose.yml[33-53]
deployment/README.md[23-32]
README.md[55-76]

Agent prompt

The issue below was found during a code review. Follow the provided context and guidance below and implement a solution

## Issue description
Compose currently applies migrations automatically through the backend image command, while the documentation says it does not and instructs users to run Alembic again. Choose one migration owner and make all startup documentation consistent with it, avoiding concurrent first-boot migrations.

## Issue Context
The Compose backend service does not override the Dockerfile command, so `alembic upgrade head` starts automatically before Uvicorn.

## Fix Focus Areas
- deployment/README.md[28-36]
- README.md[55-76]
- docs/onboarding.md[5-10]
- apps/Backend/Dockerfile[11-18]

ⓘ Copy this prompt and use it to remediate the issue with your preferred AI generation tools

---

Context sources

Review mode: ⚖️ Balanced

Tip of the day

💡 Did you know, you can describe a rule in plain language on the Rules page and Qodo drafts it for you

More tips ↗ | Customize Qodo ↗ | Qodo docs ↗

[qodo-code-review]

1. Gateway port breaks admin api 🐞 Bug ≡ Correctness

Changing the documented GATEWAY_PORT only changes the host port, while the Administration FE image
compiles its API origin as http://localhost:8080. Opening /admin on the configured port
therefore still sends authentication and API requests to port 8080, where the gateway may not be
listening.

Agent Prompt

## Issue description
The documentation advertises `GATEWAY_PORT` customization, but the Administration FE image hardcodes port 8080 into its compiled API origin. Make the configured public origin available during the image build or document and enforce the required matching configuration.

## Issue Context
Astro embeds `PUBLIC_ORIGIN` at build time. A runtime Compose environment value cannot modify the already-built static bundle.

## Fix Focus Areas
- README.md[98-104]
- deployment/docker-compose.yml[61-74]
- apps/Administration-FE/Dockerfile[1-9]
- deployment/.env.example[3-5]

ⓘ Copy this prompt and use it to remediate the issue with your preferred AI generation tools

[qodo-code-review]

2. Provision command misses container 🐞 Bug ≡ Correctness

The Docker Compose quick start tells users to run flycatch-provision-admin directly on the host,
although this workflow installs the executable only inside the backend image. Users following these
instructions receive a command-not-found error unless they separately install the backend package.

Agent Prompt

## Issue description
The Docker Compose quick start presents the later-staff provisioning executable as a host command, but the setup does not install the Backend package on the host. Prefix it with the same Compose `exec backend` command used for the other Backend CLIs.

## Issue Context
The onboarding document already demonstrates the container-qualified form, and the executable is installed by the Backend image from its Python package entry point.

## Fix Focus Areas
- README.md[88-88]
- docs/onboarding.md[27-27]

ⓘ Copy this prompt and use it to remediate the issue with your preferred AI generation tools

[qodo-code-review]

3. Compose already applies migrations 🐞 Bug ☼ Reliability

The new instructions claim Compose does not apply migrations and direct users to execute Alembic
after startup, but the backend container already runs alembic upgrade head as its startup command.
On first boot, executing the documented command while the container startup migration is still
running can launch two migrations against the same database and fail on conflicting schema changes.

Agent Prompt

## Issue description
Compose currently applies migrations automatically through the backend image command, while the documentation says it does not and instructs users to run Alembic again. Choose one migration owner and make all startup documentation consistent with it, avoiding concurrent first-boot migrations.

## Issue Context
The Compose backend service does not override the Dockerfile command, so `alembic upgrade head` starts automatically before Uvicorn.

## Fix Focus Areas
- deployment/README.md[28-36]
- README.md[55-76]
- docs/onboarding.md[5-10]
- apps/Backend/Dockerfile[11-18]

ⓘ Copy this prompt and use it to remediate the issue with your preferred AI generation tools