If you want to install some third party tools with Composer, it is recommended to install them in their dedicated directory. PHPStan and PHP-CS-Fixer are already installed in the tools directory.

We suggest to:

1. create a composer.json which requires only this tool in tools/<tool name>/composer.json;

2. create an executable symbolic link to the tool from the root directory of the project: ln -s ../<tool name>/vendor/bin/<tool bin> tools/bin/<tool bin>;

[!NOTE] Relative symlinks works here, because the first part of the command is relative to the second part, not to the current directory.

Since tools/bin path is appended to the $PATH, tools will be available globally in the builder container.

If you want to rename the application directory, or even move its content to the root directory, you have to edit each reference to it. Theses references represent each application entry point, whether it be over HTTP or CLI. Usually, there is three places where you need to do it:

• In Nginx configuration file: infrastructure/docker/services/php/frontend/etc/nginx/nginx.conf. You need to update http.server.root option to the new path. For example:

  - root /var/www/application/public; + root /var/www/public;

• In all workers configuration file: infrastructure/docker/docker-compose.worker.yml:

  - command: php -d memory_limit=1G /var/www/application/bin/console messenger:consume async --memory-limit=128M + command: php -d memory_limit=1G /var/www/bin/console messenger:consume async --memory-limit=128M

• In the builder, to land in the right directory directly: infrastructure/docker/services/php/Dockerfile:

  - WORKDIR /var/www/application + WORKDIR /var/www

[!NOTE] this cookbook documents the integration of webpack 5+. For older version of webpack, use previous version of the docker starter.

If you want to use Webpack Encore in a Symfony project,

1. Follow instructions on symfony.com to install webpack encore.

   You will need to follow these instructions too.

2. Create a new service for encore:

   Add the following content to the docker-compose.yml file:

   services: encore: build: context: services/php target: builder volumes: - "../..:/var/www:cached" command: >  yarn run dev-server  --hot  --host 0.0.0.0  --public https://encore.${PROJECT_ROOT_DOMAIN}  --allowed-hosts ${PROJECT_ROOT_DOMAIN}  --allowed-hosts encore.${PROJECT_ROOT_DOMAIN}  --client-web-socket-url-hostname encore.${PROJECT_ROOT_DOMAIN}  --client-web-socket-url-port 443  --client-web-socket-url-protocol wss  --server-type http  labels: - "project-name=${PROJECT_NAME}" - "traefik.enable=true" - "traefik.http.routers.${PROJECT_NAME}-encore.rule=Host(`encore.${PROJECT_ROOT_DOMAIN}`)" - "traefik.http.routers.${PROJECT_NAME}-encore.tls=true" - "traefik.http.services.encore.loadbalancer.server.port=8000" healthcheck: test: ["CMD", "curl", "-f", "http://localhost:8000/build/app.css"] profiles: - default

If the assets are not reachable, you may accept self-signed certificate. To do so, open a new tab at https://encore.app.test and click on accept.

1. Follow instructions on symfony.com to install AssetMapper.

2. Remove this block in the infrastructure/docker/services/php/frontend/etc/nginx/nginx.conf file:

   location ~* \.(jpg|jpeg|png|gif|ico|css|js|svg)$ { access_log off; add_header Cache-Control "no-cache"; } 

3. Remove these lines in the infrastructure/docker/services/php/Dockerfile file:

   SHELL ["/bin/bash", "-o", "pipefail", "-c"] - ARG NODEJS_VERSION=18.x - RUN curl -s https://deb.nodesource.com/gpgkey/nodesource.gpg.key | gpg --dearmor > /usr/share/keyrings/nodesource.gpg \ - && echo "deb [signed-by=/usr/share/keyrings/nodesource.gpg] https://deb.nodesource.com/node_${NODEJS_VERSION} bullseye main" > /etc/apt/sources.list.d/nodejs.list # Default toys RUN apt-get update \ && apt-get install -y --no-install-recommends \ git \ make \ - nodejs \ sudo \ unzip \ && apt-get clean \ - && npm install -g yarn@1.22 \ && rm -rf /var/lib/apt/lists/* /tmp/* /var/tmp/* /usr/share/doc/*

In order to use Elasticsearch and Kibana, you should add the following content to the docker-compose.yml file:

volumes: elasticsearch-data: {} services: elasticsearch: image: elasticsearch:7.8.0 volumes: - elasticsearch-data:/usr/share/elasticsearch/data environment: - "discovery.type=single-node" labels: - "traefik.enable=true" - "project-name=${PROJECT_NAME}" - "traefik.http.routers.${PROJECT_NAME}-elasticsearch.rule=Host(`elasticsearch.${PROJECT_ROOT_DOMAIN}`)" - "traefik.http.routers.${PROJECT_NAME}-elasticsearch.tls=true" healthcheck: test: "curl --fail http://localhost:9200/_cat/health || exit 1" interval: 5s timeout: 5s retries: 5 profiles: - default kibana: image: kibana:7.8.0 depends_on: - elasticsearch labels: - "traefik.enable=true" - "project-name=${PROJECT_NAME}" - "traefik.http.routers.${PROJECT_NAME}-kibana.rule=Host(`kibana.${PROJECT_ROOT_DOMAIN}`)" - "traefik.http.routers.${PROJECT_NAME}-kibana.tls=true" profiles: - default

Then, you will be able to browse:

• https://kibana.<root_domain>
• https://elasticsearch.<root_domain>

In your application, you can use the following configuration:

• scheme: http;
• host: elasticsearch;
• port: 9200.

Add the php extension gd to infrastructure/docker/services/php/Dockerfile

php${PHP_VERSION}-gd \ 

If you want to create a new Sylius project, you need to enter a builder (inv builder) and run the following commands

1. Remove the application folder:

   cd .. rm -rf application/*

2. Create a new project:

   composer create-project sylius/sylius-standard application

3. Configure the .env

   sed -i 's#DATABASE_URL.*#DATABASE_URL=postgresql://app:app@postgres:5432/app\?serverVersion=12\&charset=utf8#' application/.env

In order to use RabbitMQ and its dashboard, you should add a new service:

# services/rabbitmq/Dockerfile FROM rabbitmq:3-management-alpine COPY etc/. /etc/

And you can add specific RabbitMQ configuration in the services/rabbitmq/etc/rabbitmq/rabbitmq.conf file:

# services/rabbitmq/etc/rabbitmq/rabbitmq.conf vm_memory_high_watermark.absolute = 1GB 

Finally, add the following content to the docker-compose.yml file:

volumes: rabbitmq-data: {} services: rabbitmq: build: services/rabbitmq volumes: - rabbitmq-data:/var/lib/rabbitmq labels: - "traefik.enable=true" - "project-name=${PROJECT_NAME}" - "traefik.http.routers.${PROJECT_NAME}-rabbitmq.rule=Host(`rabbitmq.${PROJECT_ROOT_DOMAIN}`)" - "traefik.http.routers.${PROJECT_NAME}-rabbitmq.tls=true" - "traefik.http.services.rabbitmq.loadbalancer.server.port=15672" healthcheck: test: "rabbitmqctl eval '{ true, rabbit_app_booted_and_running } = { rabbit:is_booted(node()), rabbit_app_booted_and_running }, { [], no_alarms } = { rabbit:alarms(), no_alarms }, [] /= rabbit_networking:active_listeners(), rabbitmq_node_is_healthy.' || exit 1" interval: 5s timeout: 5s retries: 5 profiles: - default

In order to publish and consume messages with PHP, you need to install the php${PHP_VERSION}-amqp in the php image.

Then, you will be able to browse:

• https://rabbitmq.<root_domain> (username: guest, password: guest)

In your application, you can use the following configuration:

• host: rabbitmq;
• username: guest;
• password: guest;
• port: rabbitmq.

For example in Symfony you can use: MESSENGER_TRANSPORT_DSN=amqp://guest:guest@rabbitmq:5672/%2f/messages.

In order to use Redis and its dashboard, you should add the following content to the docker-compose.yml file:

volumes: redis-data: {} redis-insight-data: {} services: redis: image: redis:5 healthcheck: test: ["CMD", "redis-cli", "ping"] interval: 5s timeout: 5s retries: 5 volumes: - "redis-data:/data" profiles: - default redis-insight: image: redislabs/redisinsight volumes: - "redis-insight-data:/db" labels: - "traefik.enable=true" - "project-name=${PROJECT_NAME}" - "traefik.http.routers.${PROJECT_NAME}-redis.rule=Host(`redis.${PROJECT_ROOT_DOMAIN}`)" - "traefik.http.routers.${PROJECT_NAME}-redis.tls=true" profiles: - default 

In order to communicate with Redis, you need to install the php${PHP_VERSION}-redis in the php image.

Then, you will be able to browse:

• https://redis.<root_domain>

In your application, you can use the following configuration:

• host: redis;
• port: 6379.

In order to use Mailpit and its dashboard, you should add the following content to the docker-compose.yml file:

services: mail: image: axllent/mailpit environment: - MP_SMTP_BIND_ADDR=0.0.0.0:25 labels: - "traefik.enable=true" - "project-name=${PROJECT_NAME}" - "traefik.http.routers.${PROJECT_NAME}-mail.rule=Host(`mail.${PROJECT_ROOT_DOMAIN}`)" - "traefik.http.routers.${PROJECT_NAME}-mail.tls=true" - "traefik.http.services.mail.loadbalancer.server.port=8025" profiles: - default

Then, you will be able to browse:

• https://mail.<root_domain>

In your application, you can use the following configuration:

• scheme: smtp;
• host: mail;
• port: 25.

For example in Symfony you can use: MAILER_DSN=smtp://mail:25.

In order to use Mercure, you should add the following content to the docker-compose.yml file:

services: mercure: image: dunglas/mercure environment: - "MERCURE_PUBLISHER_JWT_KEY=password" - "MERCURE_SUBSCRIBER_JWT_KEY=password" - "ALLOW_ANONYMOUS=1" - "CORS_ALLOWED_ORIGINS=*" labels: - "traefik.enable=true" - "project-name=${PROJECT_NAME}" - "traefik.http.routers.${PROJECT_NAME}-mercure.rule=Host(`mercure.${PROJECT_ROOT_DOMAIN}`)" - "traefik.http.routers.${PROJECT_NAME}-mercure.tls=true" profiles: - default

If you are using Symfony, you must put the following configuration in the .env file:

MERCURE_PUBLISH_URL=http://mercure/.well-known/mercure MERCURE_JWT_TOKEN=eyJhbGciOiJIUzI1NiIsInR5cCI6IkpXVCJ9.eyJtZXJjdXJlIjp7InN1YnNjcmliZSI6W10sInB1Ymxpc2giOltdfX0.t9ZVMwTzmyjVs0u9s6MI7-oiXP-ywdihbAfPlghTBeQ 

In order to use redirection.io, you should add the following content to the docker-compose.yml file to run the agent:

services: redirectionio-agent: build: services/redirectionio-agent

Add the following file infrastructure/docker/services/redirectionio-agent/Dockerfile:

FROM alpine:3.12 AS alpine WORKDIR /tmp RUN apk add --no-cache wget ca-certificates \ && wget https://packages.redirection.io/dist/stable/2/any/redirectionio-agent-latest_any_amd64.tar.gz \ && tar -xzvf redirectionio-agent-latest_any_amd64.tar.gz FROM scratch # Binary copied from tar COPY --from=alpine /tmp/redirection-agent/redirectionio-agent /usr/local/bin/redirectionio-agent # Configuration, can be replaced by your own COPY etc /etc # Root SSL Certificates, needed as we do HTTPS requests to our service COPY --from=alpine /etc/ssl/certs/ca-certificates.crt /etc/ssl/certs/ CMD ["/usr/local/bin/redirectionio-agent"]

Add infrastructure/docker/services/redirectionio-agent/etc/redirectionio/agent.yml:

instance_name: "my-instance-dev" ### You may want to change this listen: 0.0.0.0:10301

Then you'll need wget. In infrastructure/docker/services/php/Dockerfile, in stage frontend:

RUN apt-get update \ && apt-get install -y --no-install-recommends \ wget \ && apt-get clean \ && rm -rf /var/lib/apt/lists/* /tmp/* /var/tmp/* /usr/share/doc/*

You can group this command with another one.

Then, after installing nginx, you need to install the module:

RUN wget -q -O - https://packages.redirection.io/gpg.key | gpg --dearmor > /usr/share/keyrings/redirection.io.gpg \ && echo "deb [signed-by=/usr/share/keyrings/redirection.io.gpg] https://packages.redirection.io/deb/stable/2 focal main" | tee -a /etc/apt/sources.list.d/packages_redirection_io_deb.list \ && apt-get update \ && apt-get install libnginx-mod-redirectionio \ && apt-get clean \ && rm -rf /var/lib/apt/lists/* /tmp/* /var/tmp/* /usr/share/doc/*

Finally, you need to edit infrastructure/docker/services/php/frontend/etc/nginx/nginx.conf to add the following configuration in the server block:

redirectionio_pass redirectionio-agent:10301; redirectionio_project_key "AAAAAAAAAAAAAAAA:BBBBBBBBBBBBBBBB"; 

Don't forget to change the project key.

In order to use Blackfire.io, you should add the following content to the docker-compose.yml file to run the agent:

services: blackfire: image: blackfire/blackfire environment: BLACKFIRE_SERVER_ID: FIXME BLACKFIRE_SERVER_TOKEN: FIXME BLACKFIRE_CLIENT_ID: FIXME BLACKFIRE_CLIENT_TOKEN: FIXME profiles: - default 

Then you'll need wget. In infrastructure/docker/services/php/Dockerfile, in stage base:

RUN apt-get update \ && apt-get install -y --no-install-recommends \ wget \ && apt-get clean \ && rm -rf /var/lib/apt/lists/* /tmp/* /var/tmp/* /usr/share/doc/*

You can group this command with another one.

Then, after installing PHP, you need to install the probe:

RUN wget -q -O - https://packages.blackfire.io/gpg.key | gpg --dearmor > /usr/share/keyrings/blackfire.io.gpg \ && sh -c 'echo "deb [signed-by=/usr/share/keyrings/blackfire.io.gpg] http://packages.blackfire.io/debian any main" > /etc/apt/sources.list.d/blackfire.list' \ && apt-get update \ && apt-get install -y --no-install-recommends \ blackfire-php \ && apt-get clean \ && rm -rf /var/lib/apt/lists/* /tmp/* /var/tmp/* /usr/share/doc/* \ && sed -i 's#blackfire.agent_socket.*#blackfire.agent_socket=tcp://blackfire:8707#' /etc/php/${PHP_VERSION}/mods-available/blackfire.ini

If you want to profile HTTP calls, you need to enable the probe with PHP-FPM. So in infrastructure/docker/services/php/Dockerfile:

RUN phpenmod blackfire

Here also, You can group this command with another one.

In order to set up crontab, you should add a new container:

# services/php/Dockerfile FROM php-base AS cron RUN apt-get update \ && apt-get install -y --no-install-recommends \ cron \ && apt-get clean \ && rm -rf /var/lib/apt/lists/* /tmp/* /var/tmp/* /usr/share/doc/* COPY --link cron/crontab /etc/cron.d/crontab COPY --link cron/entrypoint.sh /entrypoint.sh ENTRYPOINT ["/entrypoint.sh"] CMD ["cron", "-f"]

And you can add all your crons in the services/php/crontab file:

* * * * * php -r 'echo time().PHP_EOL;' > /tmp/cron-stdout 2>&1

And you can add the following content to the services/php/entrypoint.sh file:

#!/bin/bash set -e groupadd -g $USER_ID app useradd -M -u $USER_ID -g $USER_ID -s /bin/bash app crontab -u app /etc/cron.d/crontab # Wrapper for logs FIFO=/tmp/cron-stdout rm -f $FIFO mkfifo $FIFO chmod 0666 $FIFO while true; do cat /tmp/cron-stdout done & exec "$@"

Finally, add the following content to the docker-compose.yml file:

services: cron: build: context: services/php target: cron cache_from: - "type=registry,ref=${REGISTRY:-}/cron:cache" # depends_on: # postgres: # condition: service_healthy env_file: .env environment: USER_ID: ${USER_ID} volumes: - "../..:/var/www:cached" - "../../.home:/home/app:cached" profiles: - default

In order to set up workers, you should define their services in the docker-compose.worker.yml file:

services: worker_my_worker: <<: *worker_base command: /var/www/application/my-worker worker_date: <<: *worker_base command: watch -n 1 date

If you want to use the PHP FPM status page you need to remove a configuration block in the infrastructure/docker/services/php/frontend/etc/nginx/nginx.conf file:

- # Remove this block if you want to access to PHP FPM monitoring - # dashboarsh (on URL: /php-fpm-status). WARNING: on production, you must - # secure this page (by user IP address, with a password, for example) - location ~ ^/php-fpm-status$ { - deny all; - } -

And if your application uses the front controller pattern, and you want to see the real request URI, you also need to uncomment the following configuration block:

- # # Uncomment if you want to use /php-fpm-status endpoint **with** - # # real request URI. It may have some side effects, that's why it's - # # commented by default - # fastcgi_param SCRIPT_NAME $request_uri; + # Uncomment if you want to use /php-fpm-status endpoint **with** + # real request URI. It may have some side effects, that's why it's + # commented by default + fastcgi_param SCRIPT_NAME $request_uri;

In order to install pg_activity, you should add the following content to the infrastructure/docker/services/postgres/Dockerfile file:

RUN apt-get update \ && apt-get install -y --no-install-recommends \ pg-activity \ && apt-get clean \ && rm -rf /var/lib/apt/lists/* /tmp/* /var/tmp/* /usr/share/doc/*

Then, you can add the following content to the castor.php file:

#[AsTask(description: 'Monitor PostgreSQL', namespace: 'app:db')] function pg_activity(): void { docker_compose('exec postgres pg_activity -U app'); }

Finally you can use the following command:

castor app:db:pg-activity 

In order to use MySQL, you will need to apply this patch:

diff --git a/infrastructure/docker/docker-compose.builder.yml b/infrastructure/docker/docker-compose.builder.yml index d00f315..bdfdc65 100644 --- a/infrastructure/docker/docker-compose.builder.yml +++ b/infrastructure/docker/docker-compose.builder.yml @@ -10,7 +10,7 @@ services: builder: build: services/builder depends_on: - - postgres + - mysql environment: - COMPOSER_MEMORY_LIMIT=-1 volumes: diff --git a/infrastructure/docker/docker-compose.worker.yml b/infrastructure/docker/docker-compose.worker.yml index 2eda814..59f8fed 100644 --- a/infrastructure/docker/docker-compose.worker.yml +++ b/infrastructure/docker/docker-compose.worker.yml @@ -5,7 +5,7 @@ x-services-templates: worker_base: &worker_base build: services/worker depends_on: - - postgres + - mysql #- rabbitmq volumes: - "../..:/var/www:cached" diff --git a/infrastructure/docker/docker-compose.yml b/infrastructure/docker/docker-compose.yml index 49a2661..1804a01 100644 --- a/infrastructure/docker/docker-compose.yml +++ b/infrastructure/docker/docker-compose.yml @@ -1,7 +1,7 @@ version: '3.7' volumes: - postgres-data: {} + mysql-data: {} services: router: @@ -13,7 +13,7 @@ services: frontend: build: services/frontend depends_on: - - postgres + - mysql volumes: - "../..:/var/www:cached" labels: @@ -24,10 +24,7 @@ services: # Comment the next line to be able to access frontend via HTTP instead of HTTPS - "traefik.http.routers.${PROJECT_NAME}-frontend-unsecure.middlewares=redirect-to-https@file" - postgres: - image: postgres:16 - environment: - - POSTGRES_USER=app - - POSTGRES_PASSWORD=app + mysql: + image: mysql:8 + environment: + - MYSQL_ALLOW_EMPTY_PASSWORD=1 + healthcheck: + test: "mysqladmin ping -h localhost" + interval: 5s + timeout: 5s + retries: 10 volumes: - - postgres-data:/var/lib/postgresql/data + - mysql-data:/var/lib/mysql diff --git a/infrastructure/docker/services/php/Dockerfile b/infrastructure/docker/services/php/Dockerfile index 56e1835..95fee78 100644 --- a/infrastructure/docker/services/php/Dockerfile +++ b/infrastructure/docker/services/php/Dockerfile @@ -24,7 +24,7 @@ RUN apk add --no-cache \ php${PHP_VERSION}-intl \ php${PHP_VERSION}-mbstring \ - php${PHP_VERSION}-pgsql \ + php${PHP_VERSION}-mysql \ php${PHP_VERSION}-xml \ php${PHP_VERSION}-zip \

This starter kit is compatible with Docker for Windows, so you can enjoy native Docker experience on Windows. You will have to keep in mind some differences:

• You will be prompted to run the env vars manually if you use PowerShell.

Let's say you have a container (frontend) that responds to many hostnames: app.test, api.app.test, admin.app.test. And you have another container (builder) that needs to call the frontend with a specific hostname - or with HTTPS. This is usually the case when you have a functional test suite.

To enable this feature, you need to add extra_hosts to the builder container like so:

services: builder: # [...] extra_hosts: - "app.test:host-gateway" - "api.app.test:host-gateway" - "admin.app.test:host-gateway"

Let's say you have two projects foo and bar. You want to run both projects a the same time. And containers from foo project should be able to dialog with bar project via public network (host network).

In the foo project, you'll need to declare the bar_default network in docker-compose.yml:

networks: bar_default: external: true

Then, attach it to the the foo router:

services: router: networks: - default - bar_default

Finally, you must remove the constraints on the router so it'll be able to discover containers from another docker compose project:

--- a/infrastructure/docker/services/router/traefik/traefik.yaml +++ b/infrastructure/docker/services/router/traefik/traefik.yaml providers: docker: exposedByDefault: false - constraints: "Label(`project-name`,`{{ PROJECT_NAME }}`)" file:

Finally, you must :

1. build the project foo
2. build the project bar
3. Create the network bar_default (first time only)

   docker network create bar_default 

4. start the project foo
5. start the project bar

Migrating to FrankenPHP involves a lot of changes. You can take inspiration from the following repostory and specifically this commit.

You can use a docker registry to cache images layer, it can be useful to speed up the build process during the CI and local development.

First you need a docker registry, in following examples we will use the GitHub registry (ghcr.io).

Then add the registry to the context variable of the castor.php file:

function create_default_variables(): Context { return [ // [...] 'registry' => 'ghcr.io/your-organization/your-project', ]; }

Once you have the registry, you can push the images to the registry:

castor docker:push

Pushing image cache from a dev environment to a registry is not recommended, as cache may be sensitive to the environment and may not be compatible with other environments. It happens, for example, when you add some build args depending on your environment. It is recommended to push the cache from the CI environment.

This command will generate a bake file with the images to push from the cache_from directive of the docker-compose.yml file. If you want to add more images to push, you can add the cache_from directive to them.

services: my-service: build: cache_from: - "type=registry,ref=${REGISTRY:-}/my-service:cache"

1. Ensure that the github token have the write:packages scope:

permissions: contents: read packages: write

2. Install Docker buildx in the github action:

 - name: Set up Docker Buildx uses: docker/setup-buildx-action@v2

3. Login to the registry:

 - name: Log in to registry shell: bash run: echo "${{ secrets.GITHUB_TOKEN }}" | docker login ghcr.io -u $ --password-stdin

By default images are private in the GitHub registry, you will need to login to the registry to pull the images:

 - name: Log in to registry shell: bash run: echo "${{ secrets.GITHUB_TOKEN }}" | docker login ghcr.io -u $ --password-stdin