Docker Laravel Dev Environment

This post documents building a local Laravel development environment with Docker. Included are examples for debugging Laravel’s PHP with Xdebug using the Visual Studio Code editor. Source Code available on GitHub.

Install Laravel

In this example, we will be using the Composer Dependency Manager for PHP to install Laravel. To check if Composer is installed globally and in your PATH, enter composer --version in the CLI, for example,

composer --version
Composer version 1.4.1 2017-03-10 09:29:45

Get Composer if you need to install it.

With Composer, use the create-project command and the laravel/laravel package name followed by the directory to create the project in. The optional third argument is for a version number. For example, to install Laravel version 5.5 into a local directory such as home/laravel/mysite on the host computer, open a CLI then execute the composer create-project command from the directory where you want to create your project. For example:

cd ~/laravel

composer create-project laravel/laravel mysite "5.5.*"

Docker

Once composer is finished creating the Laravel project, we are ready to create the docker containers to host it. The following examples require both Docker and Docker Compose. Head on over to Docker, select Get Docker and the platform of your choice to install Docker on your computer. This should install both Docker and Docker Compose. The examples in this post were written while using Docker Community Edition, Version 17.09.0-ce.

Start Docker as needed and test the installation. Open a CLI and issue these commands.

docker --version

docker-compose --version

For the Windows platform with IIS installed, if port 80 is conflicting, shut down the IIS web server. Open an admin command prompt and enter net stop was

PHP Container

This dockerfile builds from the official Docker Hub PHP image. At the time of this writing, php 7.1.10 was the latest non RC version available in the library. If you want to use a different version, change the php version as needed, such as FROM php:5.6.31-fpm.

Create the app.dockerfile in the root of the laravel project. For example, home/laravel/mysite/app.dockerfile

app.dockerfile

FROM php:7.1.10-fpm

# php-fpm default WORKDIR is /var/www/html
# change it to /var/www
WORKDIR /var/www

RUN apt-get update && apt-get install -y \
    libmcrypt-dev \
    mysql-client --no-install-recommends \
    && docker-php-ext-install mcrypt pdo_mysql \
    && pecl install xdebug \
    && echo "zend_extension=$(find /usr/local/lib/php/extensions/ -name xdebug.so)\n" >> /usr/local/etc/php/conf.d/xdebug.ini \
    && echo "xdebug.remote_enable=1\n" >> /usr/local/etc/php/conf.d/xdebug.ini \
    && echo "xdebug.remote_autostart=1\n" >> /usr/local/etc/php/conf.d/xdebug.ini \
    && echo "xdebug.remote_connect_back=0\n" >> /usr/local/etc/php/conf.d/xdebug.ini \
    && echo "xdebug.remote_host=10.0.75.1\n" >> /usr/local/etc/php/conf.d/xdebug.ini \
    && echo "xdebug.remote_port=9001\n" >> /usr/local/etc/php/conf.d/xdebug.ini \
    && echo "xdebug.idekey=REMOTE\n" >> /usr/local/etc/php/conf.d/xdebug.ini

For Mac platforms, change the app.dockerfile xdebug remote host IP, e.g., xdebug.remote_host=10.254.254.254

Then create an alias for IP 10.254.254.254 to your existing subnet mask as follows:

sudo ifconfig en0 alias 10.254.254.254 255.255.255.0

If you want to remove the alias, use sudo ifconfig en0 -alias 10.254.254.254

Nginx Container

Create a nginx server block configuration file for php and the Laravel project root.

nginx.conf

server {
    listen 80;
    index index.php index.html;
    root /var/www/public;

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

    location ~ \.php$ {
        fastcgi_split_path_info ^(.+\.php)(/.+)$;
        fastcgi_pass app:9000;
        fastcgi_index index.php;
        include fastcgi_params;
        fastcgi_param SCRIPT_FILENAME $document_root$fastcgi_script_name;
        fastcgi_param PATH_INFO $fastcgi_path_info;
    }
}

This dockerfile builds from the official Docker Hub nginx image adding the nginx.conf Nginx server block configuration file to /etc/nginx/conf.d on the container.

web.dockerfile

FROM nginx:1.12

ADD nginx.conf /etc/nginx/conf.d/default.conf

The next section covers creating the docker-compose file, container build, create, start and stop. Xdebug and launch config for VS Code PHP debugging.

Docker Compose

Create a docker-compose yaml file to define the services (web, app, db) and the mysql volume. As stated in the Docker Compose file reference, The service definition contains configuration which will be applied to each container started for that service, much like passing command-line parameters to docker run.

docker-compose.yml

version: '2'

services:
  web:
    build:
      context: ./
      dockerfile: web.dockerfile
    volumes:
      - ./:/var/www
    ports:
      - "8080:80"
    links:
      - app
  app:
    build:
      context: ./
      dockerfile: app.dockerfile
    volumes:
      - ./:/var/www
    links:
      - db
    environment:
      - "DB_PORT=3306"
      - "DB_HOST=db"
  db:
    image: mysql:5.6
    volumes:
      - mysql:/var/lib/mysql
    environment:
      - "MYSQL_DATABASE=homestead"
      - "MYSQL_USER=homestead"
      - "MYSQL_PASSWORD=secret"
      - "MYSQL_ROOT_PASSWORD=secret"
    ports:
      - "33061:3306"
volumes:
  mysql:

Laravel .env

Update the Laravel project .env file as needed. In particular, the database port and app URL. In our docker-compose file, the database service (db) container port 3306 is mapped to 33061 on the host computer. The web server is mapped to port 8080 on the host computer.

.env

APP_DEBUG=true
APP_LOG_LEVEL=debug
APP_URL=http://localhost:8080

DB_CONNECTION=mysql
DB_HOST=127.0.0.1
DB_PORT=33061
DB_DATABASE=homestead
DB_USERNAME=homestead
DB_PASSWORD=secret

Build/Start Containers

Run docker-compose from the project root. The first time this is run, images are downloaded and containers are built from the definitions in the app and web dockerfiles we created earlier.

docker-compose up -d

-d (detached mode) starts the containers in the background and leaves them running. For more info, visit the docker-compose up docs.

Shutdown containers and services defined in the docker-compose file with the down command.

docker-compose down

For more info, visit the docker-compose down docs.

Remote Debugging with Xdebug and VS Code

VS Code has extensions available for debugging runtimes, add an adapter for Xdebug such as vscode-php-debug to allow PHP debugging. For more info, visit the VS Code Debugging page.

After installing vscode-php-debug, the VS Code project launch configuration file, launch.json, needs to be updated to include the properties to map the files on the server to the local machine. Add the serverSourceRoot and localSourceRoot settings to the home/laravel/mysite/.vscode/launch.json file. For example,

launch.json

{
    "version": "0.2.0",
    "configurations": [
        {
            "name": "Listen for XDebug",
            "type": "php",
            "request": "launch",
            "port": 9001,
            "serverSourceRoot": "/var/www",
            "localSourceRoot": "${workspaceRoot}",
            "log": true
        },
        {
            "name": "Launch currently open script",
            "type": "php",
            "request": "launch",
            "program": "${file}",
            "cwd": "${fileDirname}",
            "port": 9001
        }
    ]
}

Source Code

Resources

• Docker Documentation
• Painless Docker