DEV Community: Gerard Rico Botella

How to manage docker-compose Symfony project using Make

Gerard Rico Botella — Sat, 18 Jun 2022 19:19:21 +0000

In my previous post I explained how to setup docker-compose for a symfony project. Manage docker-compose projects can be anoying if we use docker/docker-compose commands for it. With Make, we can manage it in a simpler way.

What is Make?

According to the make page from GNU project website:

GNU Make is a tool which controls the generation of executables and other non-source files of a program from the program's source files.

Make gets its knowledge of how to build your program from a file called the makefile, which lists each of the non-source files and how to compute it from other files. When you write a program, you should write a makefile for it, so that it is possible to use Make to build and install the program.

A good place to learn how to use Makefiles is makefiletutorial website

How would we use Make?

As you can see in its definition, it's main pourpose is to generate files from source code, but we will use it to simplificate execution of the commands needed to manage a docker-compose symfony project.

Make's targets allows us to create aliases to other commands. For example, to run a symfony command in your container you will run something like:

docker exec -it bin/console your:command

If you need to run this command often, this could become anoying. With make, we can define the following target:

console/%
    docker exec -it bin/console $*

To use this target you simply run

make console/your:comand

That is pretty much simpler than docker's full command.

Creating our Makefile

Firs of all, we create a file name Makefile in our project root directory.

Docker related targets

The first target we are going to create is to execute docker-compose commands:

docker-compose/%:
    @USER=${USER} docker-compose $*

USER=${USER} is to tell docker-compose which user we want to use inside the container. This is needed to prevent permissions errors between host and container generated files.
To make it work, we will add the following variable at the begining of our Makefile:

USER := $(shell id -u):$(shell id -g)

With this, we are setting the user:group of our user to the USER variable.

Finally, we need to add user option to our service configuration (in docker-composer.yml) and set it to the environment variable $USER:

example_php:
    container_name: example_php
    user: $USER
    build:
      context: .
    working_dir: /var/www/app/
    volumes:
      - './:/var/www/app/'

Helper targets

To keep things simple on our daily usage, we will add the following helper targets:

up: Build and start services
start: Start services
stop: Stop services
build: Build or rebuild services
exec: Execute commands inside PHP service
bash: Execute bash inside our PHP service

up:
    @make docker-compose/"up -d"

start:
    @make docker-compose/"start"

stop:
    @make docker-compose/"stop"

build:
    @make docker-compose/build

exec/%:
    @docker exec -it ${PHP_CONTAINER} $*

bash:
    @make exec/bash

Other targets

Given the previously defined docker targets, it's easy to add targets. For example, we can add a symfony console target to run console commands:

console/%:
    @make exec/"bin/console $*"

As you can see, we use the exec target previously defined.
We can add all targets that we could need using this format.

All together

# ----------------------------------------------------------------------------
# Configuration
# ----------------------------------------------------------------------------

USER := $(shell id -u):$(shell id -g)
NGINX_CONTAINER = "example_nginx"
PHP_CONTAINER = "example_php"

# ----------------------------------------------------------------------------
# Docker
# ----------------------------------------------------------------------------

docker-compose/%:
    @USER=${USER} docker-compose $*

up:
    @make docker-compose/"up -d"

build:
    @make docker-compose/build

exec/%:
    @docker exec -it ${PHP_CONTAINER} $*

bash:
    @make exec/bash

# ----------------------------------------------------------------------------
# Composer
# ----------------------------------------------------------------------------

composer/%:
    @make exec/"composer $*"

composer-install:
    @make composer/"install"

composer-require/%:
    @make composer/"require $*"

composer-require-dev/%:
    @make composer/"require --dev $*"

# ----------------------------------------------------------------------------
# Symfony
# ----------------------------------------------------------------------------

console/%:
    @make exec/"bin/console $*"

# ----------------------------------------------------------------------------
# Tests
# ----------------------------------------------------------------------------

phpunit/%:
    @make exec/"vendor/bin/phpunit -c phpunit.xml.dist $*"

test:
    @make phpunit/" "

test/%:
    @make phpunit/"--testsuite $*"

How to use it

Set up

If you don't have built your services yet, run make up.
If services are already built, run make up

Dependencies

Run make composer-install to install all dependencies.

Run make composer-require/example/package to require packages. For example, to install ramsey/uuid, you will run make composer-require/ramsey/uuid.

Symfony commands

You can run any symfony command running make console/your:command. For example, if you need to clear cache, you will run make console/cache:clear. You can pass arguments and options wrapping command into double quotes: make console/cache:clear -e prod.

Tests

To run all suites, run make test.
If you want to run only your unit test suite, run make test/unit

How to setup docker-compose for Symfony projects

Gerard Rico Botella — Sat, 18 Jun 2022 10:54:40 +0000

[OPTIONAL] Create symfony project

For this example, we create a simple symfony project using composer create-project command using package symfony/skeleton:

composer create-project symfony/skeleton example

If you don't have composer installed, you can find how to do it in it's official website

Create PHP-FPM Dockerfile

Create a file named Dockerfile in your project root and write the following content:

FROM php:8.1-fpm

COPY --from=composer /usr/bin/composer /usr/bin/composer

In this example we are using php:8.1-fpm image from php official images but other FPM images are valid too if its PHP version satisfies symfony project requirements.

In order to manage composer dependencies, we copy composer binary from composer official image using multi-stage builds

Create nginx configuration

Create nginx.conf file in your project root and write the following content:

events {
    worker_connections 1024;
}

http {
    server {
        server_name  example.app;
        root /var/www/app/public;

        location / {
            try_files $uri /index.php$is_args$args;
        }

        location ~ ^/index\.php(/|$) {
            fastcgi_pass example_php:9000;
            fastcgi_split_path_info ^(.+\.php)(/.*)$;
            include fastcgi_params;

            fastcgi_param SCRIPT_FILENAME $realpath_root$fastcgi_script_name;
            fastcgi_param DOCUMENT_ROOT $realpath_root;

            internal;
        }

        location ~ \.php$ {
            return 404;
        }

        error_log /var/log/nginx/api_error.log;
        access_log /var/log/nginx/api_access.log;
    }
}

The important things here are:

root /var/www/app/public defines the directory where de index file is located.
fastcgi_pass example_php:9000 instructs nginx to execute PHP scripts using server example_php and port 9000.

Puting all together

To comunicate nginx with php, we create docker-compose.yaml file in project root with the following content:

services:
  example_nginx:
    container_name: example_nginx
    image: nginx:1.21.3-alpine
    restart: on-failure
    volumes:
      - './:/var/www/app:ro'
      - './nginx.conf:/etc/nginx/nginx.conf:ro'
    ports:
      - "9081:80"
    depends_on:
      - example_php

  example_php:
    container_name: example_php
    build:
      context: .
    working_dir: /var/www/app/
    volumes:
      - './:/var/www/app/'

example_nginx

image

Indicates docker-compose the image that should be used to create the container. You can find more official images here

restart

Indicates when should the container be restarted. You can find more info in compose specification

volumes

Makes files available for the service container. In this case, we are using two volumes:

'./:/var/www/app:ro' that binds project files to /var/www/app directory in readonly mode
'./nginx.conf:/etc/nginx/nginx.conf:ro' that binds nginx configuration file to /etc/nginx/nginx.conf in readonly mode

You can find more info about volumes here.

ports

Binds container port 80 to localhost 9081. This allows us to access out symfony application using URL http://localhost:9081.

You can find more info about ports here

depends_on

Expresses that this service dependens on service example_php. Remember that we configured nginx to use example_php as fastcgi_pass server.

You can find more info about depends_on here

example_php

context

Defines the path to the directory where the Dockerfile is located. In this case, we have both Dockerfile and docker-compose.yml in the same directory and that's why we simple use ..

You can find more info about build configuration here

working_dir

Sets the application root directory as working directory to simplificate running application commands using docker exec

volumes

In this service, we make all application files available in read and write mode in order to allow write operations like cache generation and install dependencies.

Runing the app

To run the app, we just need to run docker-compose up and access our app using the URL http://localhost:9081.