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.

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() {
    # Use zsh for PHP 8 and above
    if [[ "${1:0:1}" -ge "8" ]]; then
        docker exec -it php$1 zsh
    else
        docker exec -it php$1 bash
    fi
}

Helpful Info 🤓

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