Edge Proxy: Traefik 2.11 (Handles TLS termination, routing, and rate limiting).
Web Server: Caddy 2.7 (Serves the PHP application via FastCGI).
PHP Runtime: PHP 8.2-FPM (Scale out with workers php1 to php5).
Cache/Queue: Redis 7.
Observability: Jaeger (Tracing), Prometheus (Metrics).

Getting Started

Prerequisites

Docker Desktop 4.x+
PHP 8.2 CLI (optional, for host-side testing)

Local Development

To bring up the minimal development stack (Traefik, Redis, MySQL debug DB, Caddy, and one PHP worker):

docker compose up -d traefik redis mysql-debug php1 caddy

The API is accessible at:

http://localhost
https://localhost (using Traefik default cert)
http(s)://localhost/api/ (proxied with /api prefix stripped)

To start all services including multiple PHP workers and development tools (Jaeger, Portainer):

docker compose --profile dev up -d

Configuration

Configuration is primarily managed via environment variables.

The application root is located at services/nginx/app.
services/nginx/app/config.php loads configuration from the environment (requires USE_ENV=true).
php1 performs an automatic composer install on startup if AUTO_COMPOSER_INSTALL=true.

Testing

The project now uses Pest as the primary test runner in services/nginx/app.

Running Tests

All commands are run from services/nginx/app:

composer test
composer test:unit
composer test:integration
composer test:coverage

Integration tests are opt-in and should be run with required services available:

$env:RUN_INTEGRATION_TESTS='1'
composer test:integration

Run Tests Against A Cloned Live DB (Docker-Isolated)

Use the helper scripts in scripts/ to:

Clone the configured live DB into a local MySQL Docker container.
Start an isolated Redis container.
Run tests in a separate temporary PHP Docker container pointed at that clone.

PowerShell:

powershell -ExecutionPolicy Bypass -File .\scripts\clone-live-db-and-test.ps1 -Force

Bash:

FORCE=1 ./scripts/clone-live-db-and-test.sh

Optional overrides:

Test command: -TestCommand "composer test:integration" or TEST_COMMAND="composer test:integration"
Keep containers after run: -KeepContainers or KEEP_CONTAINERS=1
Skip image build: -SkipBuild or SKIP_BUILD=1
Force image rebuild: -ForceBuild or FORCE_BUILD=1

Clone Live DB Into `mysql-debug` Service

To refresh the docker-compose debug DB from live credentials in .env:

PowerShell:

powershell -ExecutionPolicy Bypass -File .\scripts\clone-live-to-debug-db.ps1 -Force

Bash:

FORCE=1 ./scripts/clone-live-to-debug-db.sh

Test Layout

tests/Unit/*: isolated unit and route-level behavior tests.
tests/Integration/*: Redis/DB-backed tests intended for Docker/CI environments.
tests/<legacy-domain>/*: legacy procedural scripts retained during migration; keep them runnable until matching Pest coverage exists.

Logs & Monitoring

Logs: docker compose logs -f [service_name] (e.g., php1, caddy, traefik).
Traefik Dashboard: http://traefik.localhost (available in dev).
Jaeger (Tracing): http://localhost:16686 (when running with --profile dev).
Portainer: http://localhost:9000 (when running with --profile dev).

API Documentation

OpenAPI: The authoritative OpenAPI 3.0 contract is at openapi.yaml.
Self-Serve Module Guide: Implementation and API guide at services/nginx/app/modules/selfserve/selfserve.md.
Writerside: Documentation projects are located in /Writerside and /Writerside2.
Generated Writerside API Reference: The active Writerside project lives in /documentation and is generated from openapi.yaml.

Writerside OpenAPI Generation Workflow

Prerequisite:

Python 3 with PyYAML (pip install pyyaml)

Run from repository root:

python scripts/generate_writerside_openapi_docs.py generate
python scripts/generate_writerside_openapi_docs.py check

Contribution rule:

Update openapi.yaml.
Regenerate docs (python scripts/generate_writerside_openapi_docs.py generate).
Verify (python scripts/generate_writerside_openapi_docs.py check).

README.md

Copenhagen Truck Wash API

Architecture & Stack