generated from bisco/codex-bootstrap
feat: build headless theatre laboratory website
This commit is contained in:
bisco
@@ -1,73 +1,138 @@
|
||||
# codex-bootstrap
|
||||
# Laboratorio Teatrale
|
||||
|
||||
A repository template for AI-assisted development with Codex.
|
||||
A warm, editorial single-page website for a contemporary theatre workshop. Wagtail
|
||||
provides an editor-friendly headless CMS, Astro renders the public site, PostgreSQL
|
||||
stores content, and Docker Compose supplies a reproducible local environment.
|
||||
|
||||
This template defines a repeatable workflow for using Codex as an autonomous coding agent that can create branches, modify code, run Docker-based tests, update documentation, write ADRs, and commit changes using Conventional Commits.
|
||||
## Architecture
|
||||
|
||||
## Purpose
|
||||
- `backend/`: Django and Wagtail admin, content models, media uploads, and the
|
||||
aggregate read-only API at `GET /api/site/home/`.
|
||||
- `frontend/`: Astro components, responsive design system, typed API adapter, and
|
||||
Italian fallback content for development when the CMS is unavailable.
|
||||
- `postgres`: persistent CMS database.
|
||||
- Docker volumes: `postgres_data` for the database and `media_data` for uploads.
|
||||
|
||||
Use this template to bootstrap repositories where Codex must operate with clear rules, minimal changes, pragmatic TDD, security guardrails, and explicit documentation requirements.
|
||||
See [the architecture document](docs/architecture.md) and
|
||||
[ADR-0001](docs/adr/0001-headless-wagtail-astro.md) for the rationale.
|
||||
|
||||
## Repository structure
|
||||
## Prerequisites
|
||||
|
||||
- Docker Engine with Docker Compose v2.
|
||||
- Ports `4321` and `8000` available on localhost.
|
||||
|
||||
No host Python or Node.js installation is required.
|
||||
|
||||
## Start locally
|
||||
|
||||
```bash
|
||||
cp .env.example .env
|
||||
docker compose up --build -d
|
||||
docker compose ps
|
||||
docker compose exec backend python manage.py seed_demo
|
||||
```
|
||||
|
||||
Open:
|
||||
|
||||
- public site: <http://localhost:4321>
|
||||
- Wagtail admin: <http://localhost:8000/admin/>
|
||||
- aggregate API: <http://localhost:8000/api/site/home/>
|
||||
|
||||
The frontend remains usable with curated fallback content if the API is unavailable.
|
||||
On first startup the backend applies migrations and collects static files before
|
||||
starting Gunicorn. Wait until `postgres`, `backend`, and `frontend` report healthy.
|
||||
|
||||
## Create an editor account
|
||||
|
||||
```bash
|
||||
docker compose exec backend python manage.py createsuperuser
|
||||
```
|
||||
|
||||
Sign in to Wagtail at <http://localhost:8000/admin/>. The public site has no user
|
||||
accounts or authentication.
|
||||
|
||||
## Demo content
|
||||
|
||||
The seed command is idempotent and creates or updates the initial home page, site
|
||||
settings, participation cards, teacher, lessons, shows, gallery entries, and local
|
||||
placeholder images:
|
||||
|
||||
```bash
|
||||
docker compose exec backend python manage.py seed_demo
|
||||
```
|
||||
|
||||
Re-run it only when you intentionally want to restore the demo records. Content edited
|
||||
after seeding may be overwritten for records managed by the command.
|
||||
|
||||
## Editing content
|
||||
|
||||
1. Open Wagtail admin and select **Pages** to edit the home hero, introduction,
|
||||
laboratory section, and the three participation cards.
|
||||
2. Select **Settings > Site settings** for the workshop name and contact details.
|
||||
3. Use **Snippets** for the teacher, lessons, shows, and gallery.
|
||||
4. Publish page changes. Snippet and settings changes are returned immediately by the
|
||||
aggregate endpoint.
|
||||
|
||||
The frontend reads `PUBLIC_CMS_API_URL`; inside Compose it defaults to
|
||||
`http://backend:8000`. Media URLs use `WAGTAILADMIN_BASE_URL` so browsers receive the
|
||||
public `http://localhost:8000` address. Change both values for another environment.
|
||||
The standard published-page endpoint is also available at `/api/v2/pages/`.
|
||||
|
||||
## Useful commands
|
||||
|
||||
```bash
|
||||
# Follow application logs
|
||||
docker compose logs -f postgres backend frontend
|
||||
|
||||
# Run database migrations
|
||||
docker compose exec backend python manage.py migrate
|
||||
|
||||
# Run all required checks in containers
|
||||
docker compose run --rm backend python manage.py test
|
||||
docker compose run --rm frontend npm run check
|
||||
docker compose run --rm frontend npm run build
|
||||
docker compose config --quiet
|
||||
|
||||
# Stop the stack without deleting content
|
||||
docker compose down
|
||||
|
||||
# Stop and permanently delete local database and uploaded media
|
||||
docker compose down --volumes
|
||||
```
|
||||
|
||||
The final command is destructive. It is useful only when intentionally resetting the
|
||||
local environment; run the seed command again after the next startup.
|
||||
|
||||
## Directory structure
|
||||
|
||||
```text
|
||||
.
|
||||
├── AGENTS.md
|
||||
├── README.md
|
||||
├── .codex/
|
||||
│ ├── project.md
|
||||
│ ├── workflow.md
|
||||
│ ├── security.md
|
||||
│ ├── quality.md
|
||||
│ ├── orchestration.md
|
||||
│ ├── prompts/
|
||||
│ │ ├── task.md
|
||||
│ │ ├── bugfix.md
|
||||
│ │ ├── refactor.md
|
||||
│ │ ├── security-review.md
|
||||
│ │ └── documentation.md
|
||||
│ ├── agents/
|
||||
│ │ ├── architect.md
|
||||
│ │ ├── developer.md
|
||||
│ │ ├── reviewer.md
|
||||
│ │ ├── security-reviewer.md
|
||||
│ │ ├── test-engineer.md
|
||||
│ │ └── documentation-writer.md
|
||||
│ └── profiles/
|
||||
│ ├── docker.md
|
||||
│ ├── ansible.md
|
||||
│ └── python.md
|
||||
└── docs/
|
||||
├── adr/
|
||||
│ └── 0000-template.md
|
||||
├── architecture.md
|
||||
├── deployment.md
|
||||
├── operations.md
|
||||
├── security.md
|
||||
├── testing.md
|
||||
└── runbook.md
|
||||
├── backend/ # Wagtail/Django CMS and API
|
||||
├── frontend/ # Astro public website
|
||||
├── docs/ # Architecture, operations, security, and ADRs
|
||||
├── docker-compose.yml
|
||||
├── .env.example
|
||||
└── README.md
|
||||
```
|
||||
|
||||
## How to use
|
||||
## Database and media backups
|
||||
|
||||
1. Copy this template into a new or existing repository.
|
||||
2. Edit `.codex/project.md` and configure:
|
||||
- project mode;
|
||||
- enabled profiles;
|
||||
- Docker-based test command;
|
||||
- branch naming rules if needed.
|
||||
3. Add project-specific details to the documentation under `docs/`.
|
||||
4. When asking Codex to work on a task, use one of the prompt templates under `.codex/prompts/`.
|
||||
Database rows and uploaded files must be backed up together:
|
||||
|
||||
## Core rules
|
||||
```bash
|
||||
mkdir -p backups/media
|
||||
docker compose stop frontend backend
|
||||
docker compose exec -T postgres sh -c 'pg_dump -U "$POSTGRES_USER" "$POSTGRES_DB"' > backups/database.sql
|
||||
docker compose cp backend:/app/media/. backups/media/
|
||||
docker compose start backend frontend
|
||||
```
|
||||
|
||||
Codex must:
|
||||
This brief maintenance window keeps database rows and uploaded files in sync. See
|
||||
[operations](docs/operations.md) for the destructive restore procedure and its
|
||||
cautions. Do not commit database dumps, `.env`, or uploaded media.
|
||||
|
||||
- start work from `develop`;
|
||||
- create a dedicated `feature/`, `fix/`, or `hotfix/` branch;
|
||||
- use pragmatic TDD;
|
||||
- keep changes minimal and focused;
|
||||
- run the configured Docker-based test command before completion;
|
||||
- update documentation and ADRs when needed;
|
||||
- produce a final report with summary, tests, risks, and rollback notes;
|
||||
- commit using Conventional Commits.
|
||||
## Production TODOs
|
||||
|
||||
This repository deliberately targets a simple, working local deployment. Before a
|
||||
public production launch, add a TLS reverse proxy, production-grade static/media
|
||||
serving, off-host backups, monitoring, and a deployment-specific secret manager.
|
||||
|
||||
Reference in New Issue
Block a user