PHPackages                             reach-digital/docker-devbox - PHPackages - PHPackages  [Skip to content](#main-content)[PHPackages](/)[Directory](/)[Categories](/categories)[Trending](/trending)[Leaderboard](/leaderboard)[Changelog](/changelog)[Analyze](/analyze)[Collections](/collections)[Log in](/login)[Sign up](/register)

1. [Directory](/)
2. /
3. [DevOps & Deployment](/categories/devops)
4. /
5. reach-digital/docker-devbox

ActiveMagento2-component[DevOps & Deployment](/categories/devops)

reach-digital/docker-devbox
===========================

Reach Digital Docker+local hybrid development environment.

v5.0.2(5mo ago)2228.0k↓41.1%4[4 PRs](https://github.com/ho-nl/docker-development-box/pulls)Apache-2.0VCLCI failing

Since Jun 3Pushed 2mo ago3 watchersCompare

[ Source](https://github.com/ho-nl/docker-development-box)[ Packagist](https://packagist.org/packages/reach-digital/docker-devbox)[ RSS](/packages/reach-digital-docker-devbox/feed)WikiDiscussions master Synced 1mo ago

READMEChangelog (10)Dependencies (1)Versions (63)Used By (0)

🐳 Reach Digital Magento 2.4 Docker+local hybrid development environment. 🐳
==========================================================================

[](#-reach-digital-magento-24-dockerlocal-hybrid-development-environment-)

Docker for services, PHP locally. No sync, no mental overhead, no performance penalties.

Services included: `php`, `nginx`, `https`, `http/2`, `varnish`, `mysql`, `elasticsearch`, `rabbitmq`, `mailcrab`.

PHP runs outside of Docker for optimal performance and being able to just run your tooling (i.e. `bin/magento`) from your local terminal.

Due to Docker VMM's improved performance, we use bind mounts to share files for the services that need it (`nginx`). We use guest-only volumes for services that don't need to share data for optimal performance (`mysql`, `elasticsearch`, etc.)

Goals
-----

[](#goals)

- It should be possible for a frontend developer without any backend skills to easily set up a development environment.
- It should be possible for a backend developer to add or upgrade services.
- It should be possible for a backend developer to propagate the changes to the rest of the team with version control.

Principles
----------

[](#principles)

- No magic: As few CLI tools that will automatically 'fix' things. Do not use wrappers around existing tools: docker / etc. Exception: php runs locally, needs to be set up.
- Declarative: Developer should define the final state instead of running upgrade scripts (hence, docker).
- Minimal: Use as few cpu cycles and memory as possible.

Requirements
------------

[](#requirements)

- Recent macOS
- Recent Docker
- Apple Silicon (for Docker VMM support)

Global installation (only once)
-------------------------------

[](#global-installation-only-once)

### Cleanup your system

[](#cleanup-your-system)

Since we're running some things locally it probably is a good time to clean some stuff up.

- Run `brew doctor` and make sure you don't have errors.
- Run `brew update` to update to the latest version.

You should not have any services running like.

- `php`: find them with `brew list | grep php`, uninstall them using `brew uninstall —f `. With the force flag you'll delete all installed versions of formula.
- `httpd`: [Disable apache](https://apple.stackexchange.com/questions/119674/disable-apache-autostart/119678)that is OSX native.  should not return anything.
- `mysql`: uninstall or disable mysql, or at least make sure it doesn't run on the default MySQL port.
- `nginx`: uninstall

Take a look at `~/.bash_profile` or `~/.zshrc` and make sure it doesn't contain any references to `$BREW_PREFIX/Cellar/php*`.

### Installing PHP and php-fpm services

[](#installing-php-and-php-fpm-services)

Since we're running a hybrid docker+local system we need to set up PHP to run locally. An `install.sh` script is provided for this, which you can run locally after cloning this repository.

For running the script directly, use:

```
# Cleans existing brew php (will not remove Valet stuff) + installs php on macOS
/bin/bash -c "$(curl -fsSL https://raw.githubusercontent.com/ho-nl/docker-development-box/master/install.sh)"
```

It will (re)install multiple php-fpm services, one for each version (port: 9072, 9073, 9074, etc.) and one for each version with xdebug (port: 9172, 9173, 9174, etc.).

#### Switching between PHP versions

[](#switching-between-php-versions)

You can switch between CLI PHP versions using `brew link`. For example to switch to 8.2:

```
brew unlink php@8.2 && brew link --force --overwrite php@8.2
```

Should now show the right version (check with `php -v`). If it doesn't there might be still be a version linked, or your ~/.bash\_profile should be cleaned up, or you need to reopen your CLI.

For easy switching between versions you can set up aliases like so:

```
alias link-php74='brew unlink php@7.4 && brew link --force --overwrite php@7.4'
alias link-php81='brew unlink php@8.1 && brew link --force --overwrite php@8.1'
alias link-php82='brew unlink php@8.2 && brew link --force --overwrite php@8.2'
alias link-php83='brew unlink php@8.3 && brew link --force --overwrite php@8.3'
alias link-php84='brew unlink php@8.4 && brew link --force --overwrite php@8.4'
```

### Install docker

[](#install-docker)

1. Install latest version of docker for mac.
2. Start Docker
3. Exclude `~/Library/Containers` from your backups
4. `brew install ctop`: can be used to show container metrics.
5. Open Docker -> Settings -> Resources, set memory to 6-8 GB
6. Open Docker -> Settings -> General, set virtual machine manager to Docker VMM

### Install local certificate

[](#install-local-certificate)

- Download the raw .pem file (Open Raw, then CMD + S):
- [./hitch/\*.localhost.reachdigital.io.pem](./hitch/*.localhost.reachdigital.io.pem)
- Open keychain.app, add this file (you can drag and drop this file in the keychain app, under the `Login` tab).
- Open certificate and trust the certificate (do this by right-clicking on the entry, choosing 'Get Info', and choose 'Always trust' under the 'Trust' section)

You are now done with the global installation 🎉

Project installation
--------------------

[](#project-installation)

This covers initially adding docker-devbox support to a Magento project; if your project already has docker-devbox support added, please refer to the projects' own README.

- Install (and commit) this package in the project: `composer require reach-digital/docker-devbox ^5.0.0`
- Install `static-content-deploy` [patch](patch/static-content-deploy.md) and remove existing static symlinked content: `rm -rf pub/static/*/*`.
- Copy the provided `docker-compose.example.yml` file to `docker-compose.yml`
    - When updating the docker-devbox package in the future, you may want to check changes in the example file to include in your project's copy.
- Change `docker-composer.yml` as required for your project and commit this file as part of your project:
    - Change the `FPM_PORT` and `FPM_XDEBUG` variables for the `nginx` service for the correct PHP version
    - You should match the MySQL docker image version to that of your production environment
- You can use [env.php](magento/env.php) as a base for your local env.php, which is drop-in compatible with all docker services:
    - Change the `crypt.key` value (take this from an existing production environment, or from the initially generated `env.php` if this is an entirely new project)
    - Change the base URLs (`system.default.web.*.base_url`) as desired

Usage
-----

[](#usage)

- Start: `docker-compose up -d`
- Logging: `ctop`
- Stop: `docker-compose down`

You now have all services set up 🎉. See individual services below to set urls, caches, etc.

**Deleting data (mysql/elasticsearch):**

To delete the data for (for example) MySQL, stop your containers and remove the associated docker volume:

```
docker-compose down
docker volume rm ${PROJECT_NAME}_mysql-mount
docker-compose up -d
```

You can use `docker-compose volumes` to see the volumes associated with your project.

Be sure to give MySQL a minute or two to re-initialize the data directory - during this time it will not accept connections.

Usage and setup
---------------

[](#usage-and-setup)

### Configuring Magento

[](#configuring-magento)

Configuration for all the services is included in the example [env.php](magento/env.php)

### How do I use xdebug?

[](#how-do-i-use-xdebug)

- Web: Xdebug should work by default when you have the [Xdebug Helper](https://chromewebstore.google.com/detail/xdebug-helper-by-jetbrain/aoelhdemabeimdhedkidlnbkfhnhgnhm)installed + PHPStorm is listening to connections.
- Command line: you can add the following alias to your `~/.bash_profile` or `~/.zshrc`, this will auto-detect your active PHP version, and let you debug using something like `phpd bin/magento ...`: ```
    alias phpd="XDEBUG_SESSION=1 php -c \$(brew --prefix)/etc/php/\$(php -v | head -n1 | cut -c 5-7)/php-xdebug.ini"

    ```
- Tests: Create a local interpreter in PhpStorm, the PHP version you're looking for should be suggested. Configure the `🐞 Xdebug path:` to enable xdebug (from the output of the installation script). The path is something like `/usr/local/Cellar/php/7.4.3/pecl/20190902/xdebug.so`. You can look up your exact path in your `php-xdebug.ini`.

### How do I set up my cron?

[](#how-do-i-set-up-my-cron)

[default setup](https://devdocs.magento.com/guides/v2.3/config-guide/cli/config-cli-subcommands-cron.html#create-the-magento-crontab)

### Where can I find logs?

[](#where-can-i-find-logs)

- For all other services, start `ctop` and press `