Docker + Leaf

Portable runtime

Run Leaf in the same environment everywhere.

Leaf can scaffold Docker support so PHP, extensions, web server config, Composer, and your app runtime stay reproducible across local development and deployment.

$ leaf create my-app --docker

leaf serve

docker compose up

Docker lets you package your application and its dependencies into lightweight, portable containers. This page covers setting up a Leaf application with Docker from scratch.

First, install Docker Desktop. After that, you can either use the Leaf CLI or set your application up manually.

Using the Leaf CLI

The easiest way to get started with Docker in your Leaf applications is to use the Leaf CLI. The create command has a --docker option that allows you to create a new Dockerized Leaf app:

leaf create my-app --docker

If you leave the flag off, leaf create will also ask whether you want Docker during the interactive prompts. Either way, Leaf sets your application up with Docker support: for MVC and API apps the web server is pointed at public/, and for Lite apps sensitive files (.env, composer manifests) are blocked from being served.

Although your app is dockerized, Leaf CLI still lets you use the serve command, and it will automatically start your application using Docker instead of the built-in server.

leaf serve

Adding Docker to existing projects

If you already have an existing Leaf application and you want to add Docker support to it, you will need to do so manually. We have provided a sample below that you can use as a reference.

This section requires you to have a basic understanding of Docker and how it works and interacts with your application. We recommend checking out the Docker documentation if you are new to Docker.

We have provided two examples below, one for Apache and one for Nginx. You can choose the one that best suits your needs.

Dockerfile

To build your Docker image, you'll use a Dockerfile. You can adjust this file to meet your specific requirements. We have example files for both Apache and Nginx running on PHP 8.3. To get started, create a docker directory in the root of your project and place the Dockerfile there.

Dockerfile Apache

FROM php:8.3-apache

COPY 000-default.conf /etc/apache2/sites-available/000-default.conf

RUN a2enmod rewrite

RUN apt-get update && apt-get install -y --no-install-recommends \
    libzip-dev \
    wget \
    git \
    unzip

RUN docker-php-ext-install zip pdo pdo_mysql

RUN curl -sS https://getcomposer.org/installer | php -- --install-dir=/usr/local/bin --filename=composer

RUN composer global require leafs/cli

RUN ln -s /root/.composer/vendor/bin/leaf /usr/local/bin/leaf

# If you have a custom PHP ini file you can uncomment this line
# COPY ./php.ini /usr/local/etc/php/php.ini

RUN apt-get purge -y g++ \
    && apt-get autoremove -y \
    && rm -rf /var/lib/apt/lists/* \
    && rm -rf /tmp/*

WORKDIR /var/www

RUN chown -R www-data:www-data /var/www

CMD ["apache2-foreground"]

Dockerfile Nginx

FROM php:8.3-fpm

COPY default.conf /etc/nginx/conf.d/default.conf

RUN apt-get update && apt-get install -y --no-install-recommends \
    libzip-dev \
    wget \
    git \
    unzip

RUN docker-php-ext-install zip pdo pdo_mysql

RUN curl -sS https://getcomposer.org/installer | php -- --install-dir=/usr/local/bin --filename=composer

RUN composer global require leafs/cli

RUN ln -s /root/.composer/vendor/bin/leaf /usr/local/bin/leaf

# If you have a custom PHP ini file you can uncomment this line
# COPY ./php.ini /usr/local/etc/php/php.ini

RUN apt-get purge -y g++ \
    && apt-get autoremove -y \
    && rm -rf /var/lib/apt/lists/* \
    && rm -rf /tmp/*

WORKDIR /var/www

RUN chown -R www-data:www-data /var/www

CMD ["php-fpm"]

docker-compose.yml

The docker-compose.yml file is used to define and run multi-container Docker applications. You can use this file to define your application's services, networks, and volumes. Create a docker-compose.yml file in the root of your project and add the following content:

services:
  application:
    build: ./docker
    ports:
      - '8080:80'
    volumes:
      - .:/var/www

Server config

The final piece of the puzzle is the server configuration file. You can use the following examples for Apache and Nginx. Depending on the web server you are using, create a configuration file in the docker directory.

Apache - 000-default.conf

<VirtualHost *:80>
    ServerAdmin webmaster@localhost
    # for MVC/API apps use /var/www/public; /var/www is for lite apps only
    DocumentRoot /var/www

    <Directory /var/www>
        Options FollowSymLinks
        AllowOverride All
        Require all granted
    </Directory>

    # never serve dotfiles (.env, .git, ...) or tooling manifests
    <FilesMatch "^(\..*|composer\.(json|lock)|alchemy\.yml|package(-lock)?\.json)$">
        Require all denied
    </FilesMatch>
    <DirectoryMatch "/\.">
        Require all denied
    </DirectoryMatch>
</VirtualHost>

Nginx - default.conf

server {
    listen 80;
    index index.php index.html;
    server_name localhost;
    error_log  /var/log/nginx/error.log;
    access_log /var/log/nginx/access.log;
    root /var/www/public;

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

    location ~ \.php$ {
        include fastcgi_params;
        fastcgi_pass php:9000;
        fastcgi_index index.php;
        fastcgi_param SCRIPT_FILENAME $document_root$fastcgi_script_name;
        fastcgi_param PATH_INFO $fastcgi_path_info;
    }
}

After adding these files, you can start your application using Docker by running the following command:

Leaf CLI

leaf serve

Docker Compose

docker compose up