Files

T

Jeppe Bundgaard 8bccd45fc8 Update README.md with comprehensive project documentation

- Replace outdated TLS certificate setup with a detailed overview of the Copenhagen Truck Wash API.
- Add sections on architecture, stack components, local development, configuration, testing, monitoring, and API documentation.
- Include instructions for running tests, logs inspection, and utilizing tools like Traefik, Jaeger, and Portainer.

2026-02-24 11:38:55 +01:00

2.6 KiB

Raw Blame History

Copenhagen Truck Wash API

Backend API for Copenhagen Truck Wash services.

Architecture & Stack

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, Caddy, and one PHP worker):

docker compose up -d traefik redis 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 uses a lightweight testing approach using procedural PHP scripts.

Running Tests

Tests are located in services/nginx/app/tests/.

From the host (requires PHP 8.2):

php services/nginx/app/tests/subusers/SelfservePermissionInitTest.php

Inside Docker (recommended for integration tests):

docker compose exec -T php1 php /var/www/html/tests/subusers/SelfservePermissionInitTest.php

Creating New Tests

Place new tests under services/nginx/app/tests/<domain>/. Every test should define the WD constant to point to the app root:

if (!defined('WD')) { define('WD', dirname(__DIR__, 2)); }

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.

2.6 KiB Raw Blame History