Installation
Prerequisites
- Docker Desktop (or Docker Engine + Compose)
- Node ≥ 18 and pnpm (for running the CLI and the Nuxt app locally)
PHP, Composer, and all API dependencies run inside Docker — nothing else to install.
1. Scaffold your project
Run the interactive CLI:
pnpm create cwa my-project
The CLI will ask four questions:
| Prompt | Options |
|---|---|
| Project name | The directory to create |
| CI/CD pipeline | GitHub Actions, GitLab CI, or none |
| Features | Navigation links, HTML content editor, image uploads, blog, nested pages, forms (multiselect) |
| Include fixtures? | Scaffolds sample content so the site works out of the box |
After answering, the CLI downloads the template, strips unused feature code from nuxt.config.ts, and generates a README.md tailored to your choices. It then offers to run docker compose up -d and pnpm install in one step — accept both.
cwa-manifest.json file hosted in the template repo. Feature options and their file exclusions are driven by this manifest, so the CLI always reflects the latest template state without needing a CLI update.pnpm create cwa@dev tracks the dev branch of the template. Use @latest (the default) for stable releases.2. Generate JWT keys
Authentication uses JWT tokens. Generate a key pair once:
docker compose exec php sh
Inside the container:
mkdir -p config/jwt
php -r "print bin2hex(random_bytes(26));"
Copy the passphrase, then copy .env to .env.local and set it:
cp .env .env.local
# Edit .env.local: JWT_PASSPHRASE=<your passphrase>
Generate the keys:
openssl genpkey -out config/jwt/private.pem -aes256 -algorithm rsa -pkeyopt rsa_keygen_bits:4096
openssl pkey -in config/jwt/private.pem -out config/jwt/public.pem -pubout
exit
3. Load fixtures
If you selected Include fixtures during setup, load them once the API container is healthy:
docker compose exec php bin/console doctrine:fixtures:load
This creates a default admin account (admin / admin) and seeds the site structure — layout, pages, and example components.
4. Start the dev server
cd my-project/app
pnpm dev
| URL | What's there |
|---|---|
https://localhost | Your Nuxt application |
https://localhost/_api | API (JSON-LD) |
https://localhost/admin | CWA admin panel |
api/frankenphp/caddy/certs/.Log in at https://localhost/login with admin / admin. Click Edit to enter edit mode and see the inline CMS.
What Docker handles automatically
When the php container starts, the entrypoint:
- Runs
composer installifvendor/is empty - Waits for PostgreSQL to be ready
- Runs pending database migrations
You never need to run these manually.
CI/CD
If you chose GitHub Actions during setup, four workflows are pre-wired in .github/workflows/:
| Workflow | Trigger | What it does |
|---|---|---|
ci.yml | Every push | Build + test; deploy review environment on PRs |
production.yml | Manual | Deploy canary or production |
cleanup.yml | PR closed | Tear down review environment |
performance.yml | Manual | Run sitespeed tests |
Images push to GHCR. The workflows use the same bin/devops/ shell scripts as the GitLab CI option. Required secrets and variables are listed in the CLAUDE.md of the template repo and in the workflow files themselves.
Manual setup (alternative)
If you prefer to create a GitHub repository first and clone from there:
With the GitHub CLI:
gh repo create my-website \
--template="components-web-app/components-web-app" \
--private --clone
Or generate from GitHub:
Then follow steps 2–4 above. You'll configure features manually rather than through the CLI.
What's next
- Your First Layout — create the Vue file for your layout
- Your First Page Template — define page regions with CwaComponentGroup
- Your First Component — build a PHP entity and matching Vue component