Installation

Prerequisites

• Docker Desktop (or Docker Engine + Compose), running, with about 4 GiB of memory for Docker. Docker Desktop sets this in Settings › Resources.
• Ports 80, 443, 3001, 5432 and 8025 free on your machine. The stack publishes Caddy on 80 and 443, the Nuxt dev server on 3001, PostgreSQL on 5432 and Mailpit, which catches the emails the API sends, on 8025. Another CWA project's running stack, a local web server, a local PostgreSQL or a local Mailpit commonly holds one.
• Node 22.13 or later and pnpm 12 (for running the CLI and the Nuxt app locally)

PHP, Composer, and all API dependencies run inside Docker — nothing else to install. The Nuxt app's own requirements, including Pinia 4, come in through pnpm install.

1. Scaffold your project

Run the interactive CLI:

pnpm create cwa my-project

It starts with a notice: CWA is a prerelease, so expect breaking changes between versions, and create-cwa collects no telemetry, it only downloads the template from GitHub. Then it asks, in this order:

A name that breaks the rule is refused at the prompt (Use lower-case letters, digits and single dashes (for example my-cwa-app)), and so is a directory with files in it ("my-cwa-app" already exists here and is not an empty directory), before anything is downloaded.

If you start the stack, the CLI checks Docker first, before it downloads anything:

• docker info must answer. If it doesn't, the CLI says: "Docker is installed but docker info failed: start Docker Desktop (or the Docker daemon)."
• Ports 80, 443, 3001, 5432 and 8025 must be free. For a port in use, it names what holds it: a container and its Compose project, with the command to stop it, or the process. For 3001, 5432 and 8025 it also names the line in compose.override.yaml to change instead.
• Under about 3.5 GiB of Docker memory, it warns, for example: "Docker has 2.0 GiB of memory; the stack needs about 4 GiB. Raise it in Docker Desktop → Settings → Resources." This is only a warning: the stack still starts.

If Docker isn't running or a port is taken, the CLI still creates the project but doesn't start the stack, and says so. Fix the problem (see Troubleshooting › Local development), then run bin/up in the project.

The CLI then downloads the template, strips the code for features you didn't pick, generates a README.md for your choices, and, if you said yes, runs bin/up in the new project (step 2).

The host install is offered only when the stack isn't started now, because app/node_modules is shared with the app container: a pnpm install on your machine under a running dev server crashes it (see Troubleshooting › Every page returns 502 or 503 after you run pnpm install on the host).

pnpm create cwa my-project -- --ref main

Answering the questions with options

Each question has an option that answers it, so it isn't asked:

For a run with no one at the keyboard:

• -y or --yes takes the default for every question no option answers: GitHub Actions, no features, fixtures, start the stack (when Docker is there and its checks pass), no host install. The project name has no default, so it's still asked for when you don't give one.
• --ci never asks anything, and implies --yes. A missing or invalid project name is an error, and a failed bin/up makes the CLI exit with 1.

pnpm create cwa my-project -- --ci --pipeline none --features all --no-start

--template-dir <path> copies the template from a local checkout instead of downloading it: the files git tracks, as a download would have them, with the features you chose. It can't be combined with --ref.

2. Let bin/up start the site

bin/up is the one command that takes the project from nothing running to a site you can sign in to. create-cwa runs it for you; run it yourself from the project root any other time:

bin/up

It works through four steps, printing how long each took:

1. Starts the stack with docker compose up -d --wait, which returns once every container answers its health check (see Docker › Waiting for the stack). The first run builds the images, installs the Composer and pnpm dependencies and migrates the database, so it takes several minutes.
2. Loads the fixtures with doctrine:fixtures:load --append: the admin account, plus the sample pages if you chose them.
3. Pre-compiles / and /login, so your first visit isn't a slow first compile.
4. Prints where to sign in, for example:

Ready in 412s.

  Site:      https://localhost
  Sign in:   https://localhost/login
  Admin:     admin / admin
  Emails:    http://localhost:8025 (Mailpit catches every email the API sends)

--append keeps what's already in the database and only creates what's missing, so running bin/up again is safe and changes nothing you've built. It does reset the admin's password and email to ADMIN_PASSWORD and ADMIN_EMAIL (admin and admin@example.com when unset) on every load, so if you changed them in the admin, run bin/up --skip-fixtures instead. The whole run has 15 minutes, which CWA_UP_TIMEOUT changes, in seconds. If a step fails, bin/up names it and prints the last 40 log lines of the services involved: see Troubleshooting › Local development.

docker compose exec php bin/console silverback:api-components:user:create --admin

Without a POSIX shell

Windows without a POSIX shell (WSL or Git Bash) can't run bin/up: there create-cwa runs docker compose up -d --wait instead and prints the fixtures command. Start the stack, wait for it, and load the fixtures yourself:

docker compose up -d --wait
docker compose exec php bin/console doctrine:fixtures:load --append

3. Open the site

There is no dev server to start: the Nuxt dev server already runs inside the app container, and Caddy proxies it:

Sign in at https://localhost/login with the admin login bin/up printed (admin / admin unless you set ADMIN_*; for development only). Click Edit to enter edit mode and see the inline CMS.

Where things live

The project root holds the two applications side by side. Every path in these docs starts at the project root.

Commands run from the project root unless a page says otherwise. PHP and Composer run only inside Docker, so PHP commands go through the php container: docker compose exec php bin/console ….

What Docker handles automatically

When the php container starts, the entrypoint:

• Runs composer install if vendor/ is empty
• Generates the JWT key pair for authentication with lexik:jwt:generate-keypair --skip-if-exists, outside production. The keys go in api/config/jwt/ (gitignored), encrypted with the JWT_PASSPHRASE in api/.env. To deploy, see Docker › JWT keys
• Waits for PostgreSQL to be ready
• Runs pending database migrations
• Runs ANALYZE to refresh PostgreSQL query statistics (keeps dev pages fast — see Troubleshooting)

The app container runs pnpm install and then the Nuxt dev server each time it starts. You never need to run these manually. Loading the fixtures is the one step the containers don't do, which is why bin/up does it after they're healthy.

CI/CD

If you chose GitHub Actions during setup, three workflows are pre-wired in .github/workflows/:

Images push to GHCR. The workflows use the same bin/devops/ shell scripts as the GitLab CI option. Required secrets and variables are documented inline in each workflow file — read those.

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, from the cloned project's root, run bin/up (step 2):

bin/up

Installing the Nuxt dependencies on your machine (pnpm install in app/) is optional, as in step 1: the app container installs them. If you want them, install before bin/up, never while the stack runs. A clone keeps every feature and all the fixtures, because nothing is stripped, so bin/up seeds the full demo site. Turning features off is up to you.

rm -rf packages/

What's next

Read Key Ideas first: it explains the terms the guides use, in a few minutes. Then Core Concepts gives the full picture of how a CWA site works, before the guides.

The template already ships a working layout (primary.vue), page template (PrimaryPageTemplate.vue) and component (Title). The guides build new ones beside them, ending with a /landing page:

• Your First Layout — a landing layout with an editable banner
• Your First Page Template — a two-column page template, and a page that uses it
• Your First Component — a Quote component: PHP entity, Vue display and admin tab
• Alternative UI Variants — several looks for the same component
• Your First Dynamic Page — news articles that share one template page, each at its own URL