Installing Magento with all the required services and server settings, all compatible with each other, can sometimes be quite a challenge. Whenever I installed it on our dev server, I always needed a colleague, a Linux guy, because I couldn’t handle the server side of things on my own. Docker solves this problem.
In this article, I won’t go into explaining what Docker actually is. It’s still fairly new to me, and I can only do the basics with Docker. I’ll focus on how to get Magento running on your localhost in a few minutes, so you can start learning or working on a real shop as soon as possible.
Please don’t treat this as a detailed guide. The whole topic is quite extensive, and if I wanted to write a complete walkthrough, it would be a huge article. Besides, the link below covers everything in much more detail. My guide is much shorter, assumes some basic knowledge on your part, and aims to describe solutions to the things I had problems with.
I’m basing this on this project (https://github.com/markshust/docker-magento), which provides a complete Docker image with everything you need. I’ll describe my minimal installation, including some basic tricks that I had to dig up painstakingly, either in video tutorials or on other websites.
Before the installation itself, you need to have Docker Desktop installed and any other instances of Apache, Nginx, MySQL and the like stopped, because this Docker setup uses the default ports.
Installation
Create a subdirectory in your home directory, e.g. ~/Sites/magento. It has to be a subdirectory of your home directory because of permissions.
Go into the magento directory and run this command
curl -s https://raw.githubusercontent.com/markshust/docker-magento/master/lib/onelinesetup | bash -s — magento.test 2.4.6-p3 community
magento.test is the domain your Magento will be available at. A .test domain is recommended because it won’t conflict with any other possible domain
2.4.6-p3 is the Magento version we are going to install
community is the open source edition
Once this command finishes, Magento is installed, the Docker containers are running, and when you navigate to https://magento.test/ you’ll see a clean Magento install.
Sample data
When you’re in the main directory, you have several helper scripts available in the bin folder, among them bin/magento. So if you want to install sample data, you can run this right from the terminal in the magento directory
bin/magento sampledata:deploy
bin/magento setup:upgrade
You can also disable 2FA so you don’t have to enter a code from your authenticator app when logging in to the admin
bin/magento module:disable Magento_TwoFactorAuth Magento_AdminAdobeImsTwoFactorAuth
Admin
You can get to the admin panel by navigating to https://magento.test/admin. You’ll find the login credentials in env/magento.env. Most likely they will be these
User: John.smith
Password: password123
I was very pleasantly surprised that this setup also includes a simple SMTP client, so you have access to all the emails Magento sends, e.g. when an order is placed. Just go to http://magento.test:1080/ in your browser.
If you’d like the emails to arrive directly in your own inbox, you can install this extension: https://github.com/mageplaza/magento-2-smtp. The only downside is that images in the emails won’t be displayed.
You can install the module through the helper script with
bin/composer require mageplaza/module-smtp
Then you can use, for example, your Gmail account to send emails.
Composer authentication
Authentication is also related to Composer. Some extensions downloaded directly from the Magento Marketplace require authentication keys. You can create them at https://commercemarketplace.adobe.com/. This gives you a public and a private key, which you then enter into the auth.json file.
In the src directory there is an auth.json.sample file. Rename it to auth.json and fill in the keys you just created. Then all that’s left is to run the command
bin/copytocontainer auth.json, which copies this file into the Docker container.
Database
If you need to log in to a graphical database interface, phpMyAdmin is available at http://localhost:8080.
If you want to use external software, I recommend Sequel Ace. At first I had trouble logging in, because I used the name of the Docker container (db) as the host name. Eventually I figured it out: the host had to be the domain I installed Magento under. So in my case
Host: magento.test
You’ll find the user, password, database name and port in env/db.env.
Xdebug
Xdebug is a great help when debugging PHP code. It lets you stop code execution at a specific line in a PHP file and step through it. You have access to all variables, and you can even change them at runtime. That way you see exactly what’s happening with your code and find bugs more easily.
Xdebug is built into this Docker image, but it isn’t enabled by default. To manage Xdebug, there is the bin/xdebug helper script.
The command bin/xdebug status
shows you the current state of Xdebug (enabled / disabled)
and the command bin/xdebug enable turns it on.
I had to go through this whole process twice, because after first running bin/xdebug enable and then bin/xdebug status, it kept reporting that it was disabled.
Next, you need to install the Xdebug extension in your development environment. I use Visual Studio Code, and the extension is available here: https://marketplace.visualstudio.com/items?itemName=xdebug.php-debug.
Then you need to install a Chrome extension – https://chrome.google.com/webstore/detail/xdebug-helper/eadndfjplgieldjbigjakmdgkmoaaaoc – and set the IDE key in its settings. The default value should be PHPSTORM, which is correct even if you use VS Code. If it doesn’t work for you, check this setting, then the setting in php.ini and in VS Code as well.
When actually debugging, you need to have this extension enabled in Chrome, set a breakpoint in VS Code, and also make sure full page cache is turned off. Otherwise the script will stop at the breakpoint only the first time.
You’ll find a more detailed guide in the documentation of this Docker image.
RabbitMq
RabbitMq is another of the services Magento uses; it’s a message broker. Let me first explain why I’m mentioning it here. I created a PayPal Sandbox account and wanted to complete an order through PayPal. Unfortunately, at the last step I got an error, and in the console I found this message
Uncaught PhpAmqpLib\Exception\AMQPProtocolChannelException: NOT_FOUND – no exchange ‘magento’ in vhost magento paypal
From this message it was clear to me that the problem had to do with RabbitMq.
So I found out that at http://localhost:15672, with the credentials from env/rabbitmq.env, I could log in directly to the RabbitMq admin. There I clicked on Exchanges and found that there really was no exchange named magento.
The solution was very simple. In the console I ran bin/magento setup:upgrade, which created the exchange, and after that the order through PayPal went through as well.
Conclusion
If you’ve gone through the whole process, you should have a working Magento with sample data and the basic components up and running, so you can start developing extensions and new modules as quickly as possible. I recommend going through the whole process a few more times so it becomes routine and you’re able to spin up a new project in a few minutes in the future.
If you ran into problems with anything, I recommend looking first in the documentation in this Docker image’s repository. If you don’t find it there, try googling a bit, and if you still can’t find a solution, get in touch with me. Maybe I’ll be able to help.