110 lines
3.7 KiB
Markdown
110 lines
3.7 KiB
Markdown
# Copenhagen Truck Wash API
|
|
|
|
Backend API for Copenhagen Truck Wash services.
|
|
|
|
## Architecture & Stack
|
|
- **Edge Proxy:** [Traefik 2.11](https://doc.traefik.io/traefik/) (Handles TLS termination, routing, and rate limiting).
|
|
- **Web Server:** [Caddy 2.7](https://caddyserver.com/) (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):
|
|
```powershell
|
|
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):
|
|
```powershell
|
|
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](https://pestphp.com/) as the primary test runner in `services/nginx/app`.
|
|
|
|
### Running Tests
|
|
All commands are run from `services/nginx/app`:
|
|
|
|
```powershell
|
|
composer test
|
|
composer test:unit
|
|
composer test:integration
|
|
composer test:coverage
|
|
```
|
|
|
|
Integration tests are opt-in and should be run with required services available:
|
|
|
|
```powershell
|
|
$env:RUN_INTEGRATION_TESTS='1'
|
|
composer test:integration
|
|
```
|
|
|
|
### Run Tests Against A Cloned Live DB (Docker-Isolated)
|
|
Use the helper scripts in `scripts/` to:
|
|
1. Clone the configured live DB into a local MySQL Docker container.
|
|
2. Start an isolated Redis container.
|
|
3. Run tests in a separate temporary PHP Docker container pointed at that clone.
|
|
|
|
PowerShell:
|
|
```powershell
|
|
powershell -ExecutionPolicy Bypass -File .\scripts\clone-live-db-and-test.ps1 -Force
|
|
```
|
|
|
|
Bash:
|
|
```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
|
|
powershell -ExecutionPolicy Bypass -File .\scripts\clone-live-to-debug-db.ps1 -Force
|
|
```
|
|
|
|
Bash:
|
|
```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`.
|
|
- **Writerside:** Documentation projects are located in `/Writerside` and `/Writerside2`.
|