Local Setup

Local setup has two goals: make each repository reproducible and make it obvious which service answered a request. Start only the stack needed for the feature, or start both when testing a cross-repository journey.

Prerequisites

• Docker Desktop with Docker Compose;
• Git;
• PowerShell;
• Node.js and pnpm for the documentation site.

The Symfony image installs Composer dependencies during its Docker build. Host PHP/Composer is optional unless you intentionally run tools outside the image.

1. Create the shared Docker network

Run once from any directory:

docker network inspect agapi *> $null
if ($LASTEXITCODE -ne 0) { docker network create agapi }

The network is external, so docker compose down does not remove it.

2. Configure and start api

Work from C:\Users\user\work\agapi\api.

Create a machine-local environment file from the list of required names, then fill values from the approved team secret source:

Copy-Item .\symfony\.env.example .\symfony\.env.local

Do not assume that example values are safe, current, or suitable for a shared environment. Keep .env.local untracked.

Start all three services:

docker compose up -d --build
docker compose ps

This starts:

• api with APP_ID=admin on host port 80;
• mobile-api with APP_ID=mobile on host port 8080;
• db-symfony-test (PostgreSQL 14.2) on host port 5435.

Verify the HTTP contexts:

Invoke-WebRequest http://localhost/healthcheck
Invoke-WebRequest http://localhost:8080/healthcheck
Invoke-WebRequest http://localhost/docs.json

If port 80, 8080, or 5435 is occupied, agree on a local port-map change. Do not commit machine-specific mappings as a product change.

3. Configure and start agapi-member-booking

Work from C:\Users\user\work\agapi\agapi-member-booking.

Copy-Item .\.env.example .\.env.local
docker compose up -d --build
docker compose ps

Fill .env.local from the approved local secret source before starting. The example file contains the names used by database, JWT, mail, SMS, Stripe, maps, and optional integrations; do not publish or reuse its values blindly.

The checked-in Compose file starts:

• web on http://localhost:8088;
• websocket on port 5555;
• PostgreSQL on host port 5432;
• pgAdmin on http://localhost:5050.

Useful checks:

Invoke-WebRequest http://localhost:8088/admin
Invoke-WebRequest http://localhost:5555/php/healthcheck.php
docker compose logs --tail 100 web websocket

The WebSocket endpoint itself is ws://localhost:5555/ws; opening it as an ordinary browser page is not a functional RPC test.

4. Start the documentation site

Work from C:\Users\user\work\agapi\docs.

pnpm install
pnpm dev

Open http://localhost:3000/docs. Production verification uses:

pnpm exec tsc --noEmit --incremental false
pnpm build

Stopping services

Run this inside each repository you started:

docker compose down

This stops containers but keeps named database volumes. Removing a volume erases local data and should be a deliberate, separately confirmed action.

When a screen cannot reach a backend

1. Confirm the correct containers are running with docker compose ps.
2. Check the browser's exact request URL and method.
3. Identify whether the action belongs to Symfony, compatibility HTTP, or RPC.
4. Check the corresponding container log.
5. Confirm API_URL, host, port, account, and token without printing secrets.
6. Check whether the two stacks are intended to use the same local dataset.