pvtl / docker-dev

A local Docker Environment for building PHP applications 🔨

LAMP Local Development Environment on Docker

What is this?   —   Installation   —   Usage   —   Docs

An everyday local development environment for PHP Developers. At Pivotal Agency, we've done a buuunnnch of R&D to find the best local dev tools for our team. This is the result of our hard work. This tool has been put to its paces everyday by our team, we hope it can also help yours.

Intro 👋

This is a set of Docker images to spin up a LAMP stack (Linux, Apache, MySQL and PHP) for developing locally. It's perfect for local development because you can very simply add new sites to specified folder and they're magically accessible as a subdomain of your chosen hostname (eg. ~/Projects/example maps to http://example.localhost/).

It includes all the required dependencies for everyday PHP development with common tools like Laravel, Wordpress and Magento (1 & 2). Specifically:

Default Services

• Apache (including HTTPS)
• PHP 8.3
  • Composer (latest)
  • Node.js (latest LTS) & NPM (latest)*
  • Yarn (latest of 1.x)*
  • PHPCS (with Wordpress code standards added)*
  • Wordpress CLI*
  • ZSH*
• Mailpit
• MariaDB 10.11 LTS

* Available in latest PHP container

Optional Services

• PHP 5.6, all 7.x and all 8.x
• Memcached 1.x
• Redis 7.2.x (BSD License)
• Blackfire (latest)

These optional services (eg. PHP 7.4) can be added in the .env file by appending them to the COMPOSE_FILE option. See .env for an example.

Prerequisites ⚠️

You'll need to install a modern version of Docker Desktop (or Docker on Linux).

Domain Mapping 🗺

You can tell Docker Dev which version of PHP to use or whether it should load code from a "public" folder (required for Laravel, WordPress Bedrock and Magento) simply by adjusting your project's URL.

It's assumed that all of your projects are stored as folders in ~/Projects/. You can use a different folder by changing the DOCUMENTROOT variable in your .env file.

Here is the the simplest form of domain mapping:

• https://<folder>.localhost will use the latest version of PHP and load the code from ~/Projects/<folder>/

Please note that PHP is upgraded yearly. If you want to use a specific version of PHP, you can specify it in the URL:

• https://<folder>.php83.localhost will use PHP 8.3

Or, if you want the code loaded from the "public" folder:

• https://<folder>.pub.localhost will use latest version of PHP and load the code from ~/Projects/<folder>/public/

Lastly, you can combine the two:

• https://<folder>.php83.pub.localhost will use PHP 8.3 and load the code from ~/Projects/<folder>/public/

Some frameworks use a different public folder name (eg. Wordpress Bedrock uses "web"). In these instances we recommend adding a symlink to the public folder:

cd ~/Projects/<folder>/
ln -s web public

Installation 🚀

Windows Users: The Docker Dev containers perform best while running inside WSL2. We'll assume you will run these commands in a WSL2 terminal (eg. Ubuntu LTS).

1. Open a terminal window
2. Create a new folder for your projects

mkdir ~/Projects
cd ~/Projects

Note: The ~/ alias points to your home folder (eg. /home/USERNAME/)

3. Clone this repo into your projects folder

git clone [email protected]:pvtl/docker-dev.git
cd docker-dev

4. Copy .env.example to .env and set the DOCUMENTROOT to your projects folder (eg. ~/Projects/)
5. Build and start the Docker containers:

docker compose up -d

For ease of use we recommend you also set up the Daily Shortcuts.

You can test if your Docker Dev environment is working correctly using a simple PHP info file.

1. Create the folder and file: ~/Projects/test/index.php
2. Edit the file and paste <?php phpinfo();
3. In your browser, open https://test.localhost. You should see the PHP info page.

Updating 🔄

To install the latest versions of all tools (eg. PHP, Redis, Node.js etc.), open a terminal window, browse to the docker-dev folder and run:

# 1. Fetch our latest updates
git pull

# 2. Erase previous containers. Your project files and DB's will be left as-is.
docker compose down --remove-orphans

# 3. Get latest images from Docker Hub
docker compose pull

# 4. Rebuild Dockerfiles from scratch (inc. pull any parent images)
docker compose build --pull --no-cache --parallel

# 5. Start the updated environment
docker compose up -d --remove-orphans

# 6. Erase any unused containers, images, volumes etc. to free disk space.
docker system prune --volumes

Common Commands 🔥

Docker must be running and these commands must be run from the Docker Dev folder (eg. ~/Projects/docker-dev).

Most of these actions can also be done in the Docker Desktop app.

Command	Description
docker compose start	Start all containers
docker compose stop	Stop all containers (keeps any config changes you've made to the containers)
docker compose up -d --build --no-cache	Recreate all containers from scratch
docker compose down --remove-orphans	Tear down all containers (MySQL data and project folders are kept)
docker compose exec php83-fpm zsh	Open a zsh terminal in the PHP 8.3 container
docker compose logs php83-fpm	View all logs for PHP-FPM 8.3
docker compose ps	Show which containers are running

Daily Shortcuts ⚡️

While the above commands work, they're a bit tedious to type out on a daily basis. You can set up terminal aliases to make life easier.

If you use ZSH, edit ~/.zshrc. Otherwise edit ~/.bashrc (or create the file if it doesn't exist).

1. Paste the code (below) at the bottom of the file. Adjust your folder path to suit.
2. Close and re-open your terminal to apply the changes
3. Try running devup or devdown

# Usage: "devup" or "devdown"
alias devup='(cd /home/USERNAME/Projects/docker-dev && docker compose start)'
alias devdown='(cd /home/USERNAME/Projects/docker-dev && docker compose stop)'

# Usage (for PHP 8.3): "devin 83"
# Simply change the numbers for your preferred PHP version (assuming it's installed/enabled)
devin() {
  docker exec -it php$1 zsh
}

Helpful Info 🤓

• General FAQ's
• Apache Web Server
• PHP
  • Blackfire PHP Profiler
  • XDebug
• MariaDB / MySQL Database
• Mailpit (Email Testing)
• Redis
• Memcached

docker-dev's Issues

Add `docker builder prune` to the Update section in Readme

Hi, we've used your stack for some years now, big thanks for that!

But each time we've updated we found ourself with some strange behaviour.
When using multiple PHP versions it happened quite often that each of the containers (php74-fpm, php81-fpm, php82-fpm) are actually built using the wrong image. The php74 was acutally running 8.1 or 8.2 and so on.

I'm not quite sure if this is an actual bug in Docker but it seems during the build it mixes up the different Dockerfile files.

The command docker builder prune was the solution for us.

Executing this before the actual build process it seems the problem is fixed.
I've built the containers multiple times without any problems.

Maybe this is something you could add to the Update section of the Readme if others are struggling as well.

WordPress domain mapping and config ?

Hello from the home of the Baguette,

First of all, thanks for the work, looks really amazing.

I played a little with it while looking to migrate from a vagrant dev env to a docker one, and stamble upon something that looks more like an interrogation than a real issue.

I have a WordPress install configured as : my-site.localhost, which default to php7.4. Works great.
my-site.php72.localhost redirects automatically to my-site.localhost, which is not the wanted behavior, as I would like to try it on PHP7.2 without changing the WordPress options.

Is there a way to achieve that ?
Or should I define a virtual host dedicated to this particular install and simply change the handler for .php files to the version of WordPress I want to try (I'm not sure on how to do that without breaking that smart domain mapping) ?

Thanks !

Add a PHP Analyzer like Phan (or any other)

Hey there,

I sometimes use Phan when I have to bump PHP version on a project, or when I get to work on some companies not-very-well maintained project, to help to not miss anything for the upcoming upgrade.

A tool like that (maybe there's a better one!) could have its place here I think.

It's just an idea, not really an issue or a request, what do you think ?

double quote generates an error

docker-dev/.env.example

Line 28 in 9bf7844

DOCKER_RESTART="\"no\""

There is a "\"no\"" instead of "no"
else I get
Error response from daemon: invalid restart policy '"no\'

(Windows)

Sendmail configuration ?

Hello,

Am I wrong to say that sendmail isn't installed be default on this bundle ?
I came across this issue while doing some dev on a Laravel project which skipped sendmail for the default smtp.

If this is the case, do you consider adding it (especially since Mailhog is there) ? Or provide any doc to install it properly ?

Thanks !

(question) Working with oAuth (Specifically google)

Hey, I wonder how (if) you all deal with google's oAuth.
For development google accepts http://localhost or http://127.0.0.1 while my app's url goes like xxx.localhost.
Thanks for insights.

Add PHPMyAdmin or Adminer ?

Hello guys. Thank you for your work.

Are there any plans to add a PHPMyAdmin or Adminer connection to easily administer the databases ?

You don't have permission to access / on this server.

When access to the localhost got (Mac os x)

"Forbidden
You don't have permission to access / on this server.
```"

Can't connect to XDebug in PHP 7.4 container

Hi!

I would like to solve an issue about xdebug and phpstorm on container php74-fpm. I tried step by step to allow xdebug in container, restart it and connect through the manual on official phpstorm documentation.

As you can see the debugger says Not installed. I have tried to add ports in docker-compose.yml and it still won't work.

There is a bash of the PHP74-fpm container where it says that Xdebug 3.0.1 is activated.

403 Forbidden when accessing info.localhost

I have a forbidden 403 error when accessing apache. All sites are in Sites/info and containers are set up

Starting XDebug on Mac

MacBook Pro Intel CPU, os 11.3.1
Docker v. 4.2.0 (70708)

Cloned docker-dev repo
Enabled php 7.4 into the .env file
Enabled xdebug as described into the docs
Configured vscode to run xdebug with this launch configuration:

{ "name": "Listen for Xdebug", "type": "php", "request": "launch", "port": 9000 },

Created a info.php page with a variable instantiation and a phpinfo() and added a breakpoint on the first line
Started xdebug via vscode
Navigated info.php page in browser

The page renders correctly, but xdebug won't stop at the breakpoint.

Repeated the procedure with another docker-based solution, same xdebug configuration, it works (so it seems to be a container-related issue?)
Tried adding different vscode configurations (e.g. adding "hostname": "0.0.0.0",) without success
Tried ssh tunneling within the container and running vscode in this, it works (but it's not a really practical solution)

Support for symlinks in document root

Is there a possibility to use symlinks inside the document root?

# /User/username/

- Projects
    + projectA
    + projectB
- Sites
    + projectA --> /User/username/Projects/projectA/public

Currently the symlink points to a directory that does not exist inside the docker container.

Error 404 not found

Hello!
I'm stuck on a 404 while trying to access to any project.
I followed the installation guide and created a new folder test with a file index.html.

If I try to go to http://test.localhost, I get a 404 Not found