In my last publishing, I talked about how I prefer to build my Laravel Docker image for production environments.

Now, I would like to share how I use Docker Compose to extend the production environment into a local environment and have some development conveniences such as xdebug, linters, and static analysis tools available to use through Compose.

As for services compounding the stack, we will have app, mysql, and redis. Each service will use a specific Docker image; the app service will use the previously built Dockerfile, while mysql and redis will look for their images on Docker Hub.

Content

• Docker Compose
• Version
• Services
  • App service
    • Directive build
    • Directive container_name
    • Directive command
    • Directive ports
    • Directive env_file
    • Directive volumes
    • Directive networks
  • MySQL service
    • Directive image
    • Directive container_name
    • Directive ports
    • Directive volumes
    • Directive environment
    • Directive networks
    • Connecting Laravel to MySQL
  • Redis service
    • Directive image
    • Directive container_name
    • Directive ports
    • Directive volumes
    • Directive networks
    • Connecting Laravel to Redis
• Volumes
• Networks

Docker Compose

Down below, there is an entire docker-compose.yml; read it carefully. YAML files strongly rely on indentation, and their directives depend entirely on the interpreter.

A good part of the directives will be explained further, but if you want to know every bit of this file, check the compose file reference doc.

---
version: "3.8"
services:
  app:
    build: .
    container_name: laravel_scaffold
    command: >-
      sh -c "
        apk add php82-pecl-xdebug && composer install ;\
        cp .docker/php.ini-development /etc/php82/php.ini ;\
        cp .docker/xdebug.ini /etc/php82/conf.d/50_xdebug.ini ;\
        php artisan serve --host 0.0.0.0 --port 80"
    ports:
      - "8000:80"
    env_file:
      - .env
    volumes:
      - .:/var/www/html:rw
    networks:
      - app_network

  mysql:
    image: mysql:8
    container_name: laravel_scaffold_db
    ports:
      - "3306:3306"
    restart: "always"
    volumes:
      - db_data:/var/lib/mysql
    environment:
      - MYSQL_DATABASE=homestead
      - MYSQL_USER=homestead
      - MYSQL_PASSWORD=secret
      - MYSQL_ROOT_PASSWORD=secret
    networks:
      - app_network

  redis:
    image: redis:6-alpine
    container_name: laravel_scaffold_cache
    ports:
      - "6379:6379"
    volumes:
      - cache_data:/data
    networks:
      - app_network

volumes:
  db_data:
    driver: "local"
  cache_data:
    driver: "local"

networks:
  app_network:
    driver: "bridge"

Version

The first step towards creating docker-compose.yml is to define the version of the file format.

version: "3.8"

The file format version is directly related to the Docker releases, which means that this version may change according to the version of the Docker engine running on your computer.

Services

Services are a set of configurations that are applied to each container at the start of that service, much like passing command-line parameters to docker run. To let Compose know that the definition of services is happening, you need to place the directive services:, right after the line defining the version, as the docker-compose up above shows.

App service

As mentioned before, the services are app, mysql, and redis. Let's dive into the app service, since this service holds some interactions with the container previously built using the Dockerfile from the last publishing.

app:
  build: .
  container_name: laravel_scaffold
  command: >-
    sh -c "
      apk add php82-pecl-xdebug && composer install ;\
      cp .docker/php.ini-development /etc/php82/php.ini ;\
      cp .docker/xdebug.ini /etc/php82/conf.d/50_xdebug.ini ;\
      php artisan serve --host 0.0.0.0 --port 80"
  ports:
    - "8000:80"
  env_file:
    - .env
  volumes:
    - .:/var/www/html:rw
  networks:
    - app_network

As the code shows, app: is both a directive and the name definition for the service. Under this service definition, we have seven configuration directives: build, container_name, command, ports, env_file, volumes, and networks.

Directive build

build: .

It tells Compose that we want to build a container when this service specification gets processed, while the . after the directive tells Compose that the container must be built from the Dockerfile that is relative to docker-compose.yml.

Remember, they have to be in the same directory, otherwise, you have to specify the path to the Dockerfile. A suggestion is to keep both the Dockerfile and docker-compose.yml at the root of the Laravel projects.

Directive container_name

container_name: laravel_scaffold

It specifies a custom container name rather than a generated default one, works for built or pulled containers, and makes it easier to identify containers from specific docker-compose stacks. In this case, it's saying that the container behind the app service should be named laravel_scaffold.

A good naming convention around container_name will help you find and manage containers easily, especially if you have a few docker-compose.yml files. This can easily grow to dozens of containers and having standardized names will help you know if a Redis container is from a Laravel or an Express.js stack.

Directive command

command: >-
  sh -c "
    apk add php82-pecl-xdebug && composer install ;\
    cp .docker/php.ini-development /etc/php82/php.ini ;\
    cp .docker/xdebug.ini /etc/php82/conf.d/50_xdebug.ini ;\
    php artisan serve --host 0.0.0.0 --port 80"

It's used to override the default command from the Dockerfile in use; looking at the first line, we can see that xdebug and composer with all dependencies got installed.

On the second line, the php.ini-development file gets copied from a local .docker folder into /etc/php82/php.ini at the container. This file contains all the configurations that PHP will run on. The content of this file was copied from PHP's official repository on GitHub.

On the third line, the xdebug.ini file gets copied from a local .docker folder into /etc/php82/conf.d/50_xdebug.ini at the container. This file contains the configurations that allow the host, your computer, to connect to the container and use xdebug. The xdebug configurations are the following.

zend_extension=xdebug.so
xdebug.mode=develop,coverage,debug,profile
xdebug.idekey=docker
xdebug.remote_handler=dbgp
xdebug.start_with_request=yes
xdebug.log=/dev/stdout
xdebug.log_level=0
xdebug.client_port=9003
xdebug.client_host=<YOUR_COMPUTER_IP>

Lastly, Laravel's standard server got started using the Artisan command-line interface. Since we overrode the Dockerfile command, a server must be started to serve the application.

This approach may seem odd at first, but this is what makes it possible to have a Dockerfile with production definitions only. Installing xdebug will allow any person working in the project to use a full-featured debugger, while the installation of all composer dependencies allows the person to use hooks, linters, static analysis tools, or any other development tool in a containerized environment.

It is helpful because it avoids people having to set up a development environment on their computers; with this approach, they just need to run the Compose stack, while the DevOps team can just build the Dockerfile and deploy it.

Directive ports

ports:
  - "8000:80"

It exposes ports in the format HOST:CONTAINER; hence, the directive is mapping port 8000 from the host to port 80 of the container.

The host port of choice is arbitrary; any available port can be used, while the container port has to match the port used to serve the application; as the third line of the command directive shows, that port is port 80.

Then, to access the application from Postman, Insomnia, or a browser, you just need to use http://localhost:8000.

Directive env_file

env_file:
  - .env

Add environment variables from a file; it can be a single value or a list. Hence, the directive is loading the .env file that is relative to docker-compose.yml.

Directive volumes

volumes:
  - .docker/xdebug.ini
  - .:/var/www/html:rw

It maps files or directories in the format SOURCE:TARGET[:MODE]. This syntax can be used to ignore or sync volumes between the host and the container and specify modes or permissions for the volumes mapped.

In the first line, we are specifying a SOURCE volume without TARGET or MODE; this syntax will ignore the file .docker/xdebug.ini. The file got ignored because we already copied him to /etc/php82/conf.d/50_xdebug.ini at the command directive, and there is no need to copy him again.

In the second line, we are syncing the directory where docker-compose.yml is into /var/www/html of the container with reading and write permission. As mentioned, docker-compose.yml is usually at the root of my Laravel projects; this means that the entire project got synced.

The second line of the volume mapping is the approach that allows live reloading in the project; in this way, you don't need to stop the container and spin it up again after changing something in the text editor or IDE. Since the volumes (directories and files) are synced, any changes made on the host will reflect in the container, and vice versa.

Directive networks

networks:
  - app_network

It specifies networks to join, referencing entries under the top-level networks key. The app_network will be defined and explained further in this article.

MySQL service

mysql:
  image: mysql:8
  container_name: laravel_scaffold_db
  ports:
    - "3306:3306"
  volumes:
    - db_data:/var/lib/mysql
  environment:
    - MYSQL_DATABASE=homestead
    - MYSQL_USER=homestead
    - MYSQL_PASSWORD=secret
    - MYSQL_ROOT_PASSWORD=secret
  networks:
    - app_network

As mentioned before, mysql: is both a directive and the name definition for the service. Under this service definition, we have six configuration directives: image, container_name, ports, environment, and networks.

Directive image

image: mysql:8

Specify the image to start the container from, usually a repository with a tag. Bear in mind that if the tag is not present, the Docker engine will look for the repository plus the latest tag. In case the image does not exist, Compose attempts to pull it, usually from Docker Hub, unless you have also specified build, in which case it builds it using the specified options and tags it with the specified tag.

In case you have a custom registry configured, such as AWS ECR, the Docker engine will look into ECR and try to find an image mysql with tag 8 and only if an image cannot be found in ECR will it fall back to Docker Hub, so be careful with your image's naming convention.

Directive container_name

container_name: laravel_scaffold_db

It specifies a custom container name rather than a generated default one; it works for built or pulled containers. In this case, it's defining the container name behind the mysql service as laravel_scaffold_db.

Directive ports

ports:
  - "3306:3306"

The directive maps port 3306 from the host to port 3306 of the container. To access the application from MySQL Workbench, DBeaver, or DataGrip you just need to use localhost as the host at port 3306.

Directive volumes

volumes:
  - db_data:/var/lib/mysql

Here, we are using db_data: as a named volume in the top-level volumes key. The definition of the volume will be explained further, but basically, Compose gets instructed to create a db_data directory at /var/lib/docker/volumes.

Since /var/lib/docker/volumes/db_data is being created the result of the volume mounting is that everything crated by MySQL at /var/lib/mysql will be synced to the db_data directory, this includes the databases and the data stored in them.

Directive environment

environment:
  - MYSQL_DATABASE=homestead
  - MYSQL_USER=homestead
  - MYSQL_PASSWORD=secret
  - MYSQL_ROOT_PASSWORD=secret

Defines environment variables for the container; here we are defining MySQL variables that define the default database, user, password, and root password. Note that the environment variables follow the same patter that the .env file present in the Laravel project that we loaded at the app service using the env_file directive.

Directive networks

networks:
  - app_network

It specifies networks to join, referencing entries under the top-level networks key. The app_network will be defined and explained further in this article.

Connecting Laravel to MySQL

With the app service defined and the Laravel application ready to run, we need to update Laravel's .env file to connect to this MySQL service. For that, it's necessary to change the environment variable DB_HOST=127.0.0.1 to DB_HOST=mysql.

As you may have noticed, we are using the service name mysql as the host because Docker resolves the service name into a network connection and further into an IP address that can be used between app and mysql services containers.

Redis service

redis:
  image: redis:alpine
  container_name: laravel_scaffold_cache
  ports:
    - "6379:6379"
  volumes:
    - cache_data:/data
  networks:
    - app_network

As mentioned before, redis: is both a directive and the name definition for the service. Under this service definition, we have five configuration directives: image, container_name, ports, environment, and networks.

Directive image

image: redis:alpine

As mentioned, this directive specifies the image to start the container from a repository, and in case the image does not exist, Compose will attempt to pull it from Docker Hub.

Directive container_name

container_name: laravel_scaffold_cache

It specifies a custom container name rather than a generated default one; it works for built or pulled containers. In this case, it's defining the container name behind the redis service as laravel_scaffold_cache.

Directive ports

ports:
  - "6379:6379"

The directive maps port 6379 from the host to port 3306 of the container. To access the application from RedisInsight, or RDM (Redis Desktop Manager), you just need to use localhost as the host at port 6379.

Directive volumes

volumes:
  - cache_data:/data

Here, we are using cache_data: as a named volume in the top-level volumes key. The definition of the volume will be explained further, but basically, Compose gets instructed to create a cache_data directory at /var/lib/docker/volumes.

Since /var/lib/docker/volumes/cache_data is being created the result of the volume mounting is that everything crated by Redis at /data will be synced to the cache_data directory, this includes the databases and the hashes stored in them.

Directive networks

networks:
  - app_network

It specifies networks to join, referencing entries under the top-level networks key. The app_network will be defined and explained further in this article.

Connecting Laravel to Redis

To connect to the Redis service, we need to update Laravel's .env file, changing the environment variable from REDIS_HOST=127.0.0.1 to REDIS_HOST=redis. As mentioned, we have to use the service name as the host, so Docker can resolve the service name into a network connection that can be used between app and redis services containers.

Volumes

volumes:
  db_data:
    driver: "local"
  cache_data:
    driver: "local"

Here we have what Docker Compose defines as top-level volumes; these volumes get defined outside the services. This approach is used when a high level of reuse is needed or if volumes have a lifecycle that differs from the service.

For both volumes, we are defining the named volumes db_data:, and cache_data:. Similar to the service, these are directives and name definitions; the volume definitions also have the directive driver: set to local, which means that this volume will be attached to the host disk.

Since the driver is local, the result will be /var/lib/docker/volumes/db_data and /var/lib/docker/volumes/cache_data directories getting created. After attaching these volumes to a service, everything created by the service will be synced to the previously created directories.

Furthermore, the data on volumes will not be deleted when the service using the volume gets restarted, recreated, or deleted, and this is a behavior that we want when using volumes with persistent data services, such as MySQL and Redis.

Networks

networks:
  app_network:
    driver: "bridge"

Here we are defining top-level networks; this network got defined outside the service. The network definition also has the directive driver: set to bridge, which means that services attached to this network get bridged to each other. This approach is what allows app services to connect to MySQL and redis services without any special configuration.

Now your docker-compose.yml is finally done, and you can build and run all the containers from it by executing docker-compose up in your terminal. To run the containers in the background, hiding logs and outputs, you can do it by executing docker-compose up -d in your terminal.

Happy coding!