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 directory and they're magically accessible as a subdomain of your chosen hostname (eg. eg. ~/Sites/info maps to http://info.localhost/).

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

Default:

• Apache (including HTTPS)
• PHP 8.1
  • Composer (latest)
  • Node.js (16.x) & NPM (latest)*
  • Yarn (latest)*
  • PHPCS (with Wordpress code standards added)*
  • Wordpress CLI*
  • ZSH*
• Mailhog (latest)
• MariaDB 10.3

Optional:

• PHP 5.6, 7.0, 7.1, 7.2, 7.3 and 7.4
• Memcached 1.x
• Redis 7.x
• Blackfire (latest)

* Available in latest 2x PHP containers

The environment features clever domain mapping to allow you to run code for various platforms. Sites are accessible from the following URLs (by default it's http://<website>.localhost, however APACHE_HOSTNAME can modified in .env to point to a different hostname):

• http://classic-php.php56.{APACHE_HOSTNAME} (eg. http://classic-php.php56.localhost)
  • Will map to ~/Sites/classic-php and use PHP 5.6
• http://laravel.php74.pub.{APACHE_HOSTNAME}
  • Will map to ~/Sites/laravel/public and use PHP 7.4
• http://another-project.{APACHE_HOSTNAME}
  • Will map to ~/Sites/another-project and use the default version of PHP (currently 8.0)

Optional services (eg. PHP 5.6, PHP 7.4) can be added in the .env file by appending them to the COMPOSE_FILE option. See .env.example for an example of the syntax.

---

Prerequisites ⚠️

You'll first need to install Docker Desktop (or Docker on Linux).

---

Installation 🚀

On Windows, we strongly recommend running these commands inside a WSL2 container for best performance

# Clone the repo
git clone https://github.com/pvtl/docker-dev && cd docker-dev

# Create & update relevant config - For example:
#  - Point sites to your sites directory
#  - Set user/group ID's
#  - Add optional services (eg. extra PHP versions, PHPMyAdmin, Memcached etc)
cp .env.example .env

# Start the environment
docker-compose up -d

# The containers are now running. You can now:
# - Open a website in your browser using <DIRECTORY NAME>.{APACHE_HOSTNAME} (see domain mapping notes above)
# - Open a terminal window into one of the containers, via `docker-compose exec <CONTAINER NAME> bash`

---

Updating 🔄

Open a terminal window, browse to this project's folder and run:

# 1. Pull from Git
git pull
# 2. Erase previous containers
docker-compose down --remove-orphans
# 3. Get latest docker images
docker-compose pull
# 4. Rebuild Dockerfiles from scratch (inc. pull parent images)
docker-compose build --pull --no-cache --parallel
# 5. Start the new env
docker-compose up -d
# 6. Erase any unused containers, images, volumes etc. to free disk space.
docker system prune --volumes

This will also install the latest versions of all tools (eg. PHP, Redis, Node.js etc.)

---

Common Commands 🔥

The Docker Engine must be running and commands must be run within this repo's root.

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	Tear down all containers (MySQL data and Project files are kept)
docker-compose exec php80-fpm zsh	Open a zsh terminal in the PHP 8.0 container
docker-compose logs php80-fpm	View all logs for PHP-FPM 8.0
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. If you're using macOS, Linux or WSL you can set up Bash or ZSH aliases to make life easier.

Edit either ~/.bashrc or ~/.zshrc and paste this code block in at the bottom of the file:

# Usage: "devup" or "devdown"
# Just update the path to point to the actual location of your docker-dev folder
alias devup='(cd /home/manuel/docker-dev && docker compose start)'
alias devdown='(cd /home/manuel/docker-dev && docker compose stop)'

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

---

Further Reading

• 🚥 Connections
  • Email
  • MySQL
  • XDebug
  • Redis
  • Memcached
• ❓ FAQs
  • localhost isn't working
  • Crons
  • BrowserSync
  • CURL requests from/to LDE sites
  • HTTPS
  • BlackFire
  • Mapping a Custom Hostname to a local site
  • Changing your MySQL Root password
  • Adding custom PHP configuration
  • Using Redis as a session handler
  • How do I change the 'default' PHP container?
  • Custom domains / Testing OAuth Logins