Docker Guidelines

Purpose

This repository follows a Docker-first approach.

The application must be fully operational through Docker.

Developers should not be required to install PHP, Composer, Node.js or PostgreSQL directly on their host machine.

All project operations must be executable through Docker containers.

---

Docker First Rule

Always use Docker.

Never ask developers to run:

php
composer
symfony
npm
yarn
pnpm

directly on the host machine.

Use Makefile commands instead.

---

Infrastructure Overview

Expected containers:

app
postgres
mailcatcher
gotenberg

Optional:

node

if separated from the PHP container.

---

Application Container

The application container is responsible for:

• PHP execution
• Composer
• Symfony CLI
• PHPUnit
• PHPStan
• Linters
• Node.js tooling

The container should be the primary development environment.

---

PHP Version

Mandatory version:

PHP 8.4

Container type:

PHP-FPM

---

PostgreSQL

Database:

PostgreSQL

Use the latest stable version available.

Port mapping:

127.0.0.1:5432:5432

Requirements:

• persistent volume
• automatic initialization
• support for tests

---

Mailcatcher

Mailcatcher is mandatory.

Purpose:

• local email testing
• password reset testing
• notification testing

No external SMTP service should be required.

---

Gotenberg

Gotenberg is mandatory.

Purpose:

• PDF generation
• HTML to PDF conversion

Expected service name:

gotenberg

The application should communicate with Gotenberg through a dedicated service.

Example:

PdfGeneratorService

---

UID / GID

The local developer user is:

1000:1000

Dockerfiles must support:

ARG UID=1000
ARG GID=1000

Purpose:

• avoid permissions issues
• avoid root-owned files
• ensure cache accessibility
• ensure Composer accessibility
• ensure npm accessibility

---

Writable Directories

The following directories must remain writable:

var/
var/cache/
var/log/
vendor/
node_modules/

Generated files must remain editable by the local user.

---

Volumes

Expected persistent volumes:

postgres_data

Optional:

composer_cache
npm_cache

---

Docker Compose

The project should use:

compose.yaml

Optional:

compose.override.yaml

Avoid maintaining multiple Compose configurations without justification.

---

Environment Variables

Sensitive values must never be hardcoded.

Use:

.env
.env.local
.env.test

Provide:

.env.example

for onboarding.

---

Makefile

The Makefile is the primary entry point.

All recurring commands must be available through Make targets.

---

Mandatory Targets

Infrastructure

make build
make up
make down
make restart
make logs

---

Shell Access

make shell

Purpose:

Open a shell in the application container.

---

Composer

make composer-install
make composer-update
make composer-require

Composer must run inside Docker.

Bad:

composer install

Good:

make composer-install

---

NPM

make npm-install
make npm-build
make npm-dev

---

Doctrine

make db-create
make db-migrate
make db-diff
make fixtures

---

Testing

make test

---

Static Analysis

make phpstan

---

Linters

make lint
make lint-php
make lint-twig

---

XDebug

XDebug must be enabled.

Purpose:

• debugging
• breakpoints
• profiling

---

VSCode

The repository must provide:

docs/vscode-xdebug.md

This file must contain:

• extension requirements
• launch.json example
• path mappings

---

Debug Port

Default port:

9003

---

Example Path Mapping

Container:

/var/www/html

Host:

${workspaceFolder}

---

Symfony Commands

Symfony commands must run inside Docker.

Bad:

php bin/console cache:clear

Good:

make console CMD="cache:clear"

---

NPM Commands

NPM commands must run inside Docker.

Bad:

npm install

Good:

make npm-install

---

Database Migrations

All schema changes must use Doctrine migrations.

Never modify the database manually.

Expected workflow:

make db-diff
make db-migrate

---

Fixtures

Fixtures should provide a working development environment.

Minimum fixtures:

Admin User
Regular User

Default password:

rt0zclln

Fixtures must be executable through:

make fixtures

---

Test Environment

A dedicated test environment must exist.

Expected file:

.env.test

Tests must not use the development database.

---

CI Compatibility

All commands available locally through Makefile must be executable in CI.

CI should be able to execute:

make test
make phpstan
make lint

without modifications.

---

Docker Completion Checklist

Before validating infrastructure changes:

• Containers start successfully
• Database is reachable
• Mailcatcher is reachable
• Gotenberg is reachable
• XDebug works
• PHPUnit passes
• PHPStan passes
• Linters pass
• No permission issues
• UID/GID respected

Infrastructure must remain reproducible across machines.