This is a customized repository forked from https://github.com/markshust/docker-magento
Although this is a docker solution, your host machine will need the following:
- Docker Desktop
- PHP version 8.1
- Composer version 2
- Composer keys with access to Adobe Commerce (Magento 2 EE/B2B) on repo.magento.com or connect20-qa01.magedevteam.com
- During the install, you may be prompted to enter these keys. They can be found on your Marketplace Account
- Github Access to the magento-commerce organization
Before running, make sure you do not have any server running on ports 80, 443, 3306 or 9000. If you have apache, nginx, mysql or php-fpm running locally, be sure to stop these services so that install does not fail
# Download the Docker Compose template into the specified project directory (Ex. magento2)
curl -s https://raw.githubusercontent.com/rossbrandon/docker-magento/main/lib/template | bash -s -- magento2
# Configure env/install.env file to specify Magento version, edition, Magento install source, and if you need Luma sample data
# Example:
#MAGENTO_VERSION=2.4.4
#INSTALL_SOURCE=composer # This is the method used to install Magento only not Data Solutions extensions
#INSTALL_SAMPLE_DATA=true
# Create a DNS host entry for the site
# Default site is magento2.test. You may customize this with the MAGENTO_BASE_URL variable in env/install.env
echo "127.0.0.1 ::1 magento2.test" | sudo tee -a /etc/hosts
# Run the create script to get going!
bin/create
# Open site
open https://magento2.test
bin/bash
: Drop into the bash prompt of your Docker container. Thephpfpm
container should be mainly used to access the filesystem within Docker.bin/cache-clean
: Access the cache-clean CLI. Note the watcher is automatically started at startup inbin/start
. Ex.bin/cache-clean config full_page
bin/cli
: Run any CLI command without going into the bash prompt. Ex.bin/cli ls
bin/clinotty
: Run any CLI command with no TTY. Ex.bin/clinotty chmod u+x bin/magento
bin/cliq
: The same asbin/cli
, but pipes all output to/dev/null
. Useful for a quiet CLI, or implementing long-running processes.bin/composer
: Run the composer binary. Ex.bin/composer install
bin/copyfromcontainer
: Copy folders or files from container to host. Ex.bin/copyfromcontainer vendor
bin/copytocontainer
: Copy folders or files from host to container. Ex.bin/copytocontainer --all
bin/create
: Downloads, installs, and starts Magento with Data Solutions extensions (currently Product Recommendations and Live Search)bin/cron
: Start or stop the cron service. Ex.bin/cron start
bin/destroy
: Stops docker containers and prunes containers, networks, and volumes - Use when rebuilding entirelybin/dev-urn-catalog-generate
: Generate URN's for PHPStorm and remap paths to local host. Restart PHPStorm after running this command.bin/devconsole
: Alias forbin/n98-magerun2 dev:console
bin/devtools-cli-check
: Check & install the CLI devtools if missing from system.bin/download
: Download specific Magento version from Composer to/var/www/html
directory within the container. Ex.bin/download 2.4.2 community
bin/fixowns
: This will fix filesystem ownerships within the container.bin/fixperms
: This will fix filesystem permissions within the container.bin/grunt
: Run the grunt binary. Ex.bin/grunt exec
bin/install-b2b
: Installs Magento B2Bbin/install-datasolutions
: Installs Data Solutions extensions toextensions
directorybin/install-sampledata
: Installs Magento Luma sample databin/install-src
: Installs Magento code intosrc
directory based upon configuration in.env
bin/magento
: Run the Magento CLI. Ex:bin/magento cache:flush
bin/mysql
: Run the MySQL CLI with database config fromenv/db.env
. Ex.bin/mysql -e "EXPLAIN core_config_data"
orbin/mysql < backups/magento.sql
bin/mysqldump
: Backup the Magento database. Ex.bin/mysqldump > backups/magento.sql
bin/n98-magerun2
: Access the n98-magerun2 CLI. Ex:bin/n98-magerun2 dev:console
bin/node
: Run the node binary. Ex.bin/node --version
bin/npm
: Run the npm binary. Ex.bin/npm install
bin/pwa-studio
: (BETA) Start the PWA Studio server. Note that Chrome will throw SSL cert errors and not allow you to view the site, but Firefox will.bin/redis
: Run a command from the redis container. Ex.bin/redis redis-cli monitor
bin/remove
: Remove all containers.bin/removeall
: Remove all containers, networks, volumes, and images.bin/removevolumes
: Remove all volumes.bin/restart
: Stop and then start all containers.bin/root
: Run any CLI command as root without going into the bash prompt. Exbin/root apt-get install nano
bin/rootnotty
: Run any CLI command as root with no TTY. Exbin/rootnotty chown -R app:app /var/www/html
bin/setup
: Existing script but was customized to fit Data Solutions developer use cases and driven byenv/install.env
configurationbin/setup-grunt
: Install and configure Grunt JavaScript task runner to compile .less filesbin/setup-pwa-studio
: (BETA) Install PWA Studio (requires NodeJS and Yarn to be installed on the host machine). Pass in your base site domain, otherwise the defaultmagento2.test
will be used. Ex:bin/setup-pwa-studio magento2.test
bin/setup-composer-auth
: Setup authentication credentials for Composer.bin/setup-grunt
: Install and configure Grunt JavaScript task runner to compile .less filesbin/setup-pwa-studio
: (BETA) Install PWA Studio (requires NodeJS and Yarn to be installed on the host machine). Pass in your base site domain, otherwise the defaultmaster-7rqtwti-mfwmkrjfqvbjk.us-4.magentosite.cloud
will be used. Ex:bin/setup-pwa-studio magento2.test
bin/setup-ssl
: Generate an SSL certificate for one or more domains. Ex.bin/setup-ssl magento2.test foo.test
bin/setup-ssl-ca
: Generate a certificate authority and copy it to the host.bin/start
: Start all containers, good practice to use this instead ofdocker-compose up -d
, as it may contain additional helpers.bin/status
: Check the container status.bin/stop
: Stop all containers.bin/update
: Update your project to the most recent version ofdocker-magento
.bin/xdebug
: Disable or enable Xdebug. Accepts paramsdisable
(default) orenable
. Ex.bin/xdebug enable
For an improved developer experience, caches are automatically refreshed when related files are updated, courtesy of cache-clean. This means you can keep all of the standard Magento caches enabled, and this script will only clear the specific caches needed, and only when necessary.
To disable this functionality, uncomment the last line in the bin/start
file to disable the watcher.
The hostname of each service is the name of the service within the docker-compose.yml
file. So for example, MySQL's hostname is db
(not localhost
) when accessing it from within a Docker container. Elasticsearch's hostname is elasticsearch
.
To connect to the MySQL CLI tool of the Docker instance, run:
bin/mysql
You can use the bin/mysql
script to import a database, for example a file stored in your local host directory at magento.sql
:
bin/mysql < magento.sql
You also can use bin/mysqldump
to export the database. The file will appear in your local host directory at magento.sql
:
bin/mysqldump > magento.sql
Getting an "Access denied, you need (at least one of) the SUPER privilege(s) for this operation." message when running one of the above lines? Try running it as root with:
bin/clinotty mysql -hdb -uroot -pmagento magento < src/backup.sql
You can also remove the DEFINER lines from the MySQL backup file with:
sed 's/\sDEFINER=`[^`]*`@`[^`]*`//g' -i src/backup.sql
First setup Magento Marketplace authentication (details in the DevDocs).
Copy src/auth.json.sample
to src/auth.json
. Then, update the username and password values with your Magento public and private keys, respectively. Finally, copy the file to the container by running bin/copytocontainer auth.json
.
View emails sent locally through Mailcatcher by visiting http://{yourdomain}:1080. During development, it's easiest to test emails using a third-party module such as [https://github.com/mageplaza/magento-2-smtp](Mageplaza's SMTP module). Set the mailserver host to mailcatcher
and port to 1080
.
Redis is now the default cache and session storage engine, and is automatically configured & enabled when running bin/setup
on new installs.
Use the following lines to enable Redis on existing installs:
Enable for Cache:
bin/magento setup:config:set --cache-backend=redis --cache-backend-redis-server=redis --cache-backend-redis-db=0
Enable for Full Page Cache:
bin/magento setup:config:set --page-cache=redis --page-cache-redis-server=redis --page-cache-redis-db=1
Enable for Session:
bin/magento setup:config:set --session-save=redis --session-save-redis-host=redis --session-save-redis-log-level=4 --session-save-redis-db=2
You may also monitor Redis by running: bin/redis redis-cli monitor
For more information about Redis usage with Magento, see the DevDocs.
Install and enable the PHP Debug extension from the Visual Studio Marketplace.
Otherwise, this project now automatically sets up Xdebug support with VS Code. If you wish to set this up manually, please see the .vscode/launch.json
file.
-
First, install the Chrome Xdebug helper. After installed, right click on the Chrome icon for it and go to Options. Under IDE Key, select PhpStorm from the list to set the IDE Key to "PHPSTORM", then click Save.
-
Next, enable Xdebug debugging in the PHP container by running:
bin/xdebug enable
. -
Then, open
PhpStorm > Preferences > PHP
and configure:CLI Interpreter
- Create a new interpreter from the
From Docker, Vagrant, VM...
list. - Select the Docker Compose option.
- For Server, select
Docker
. If you don't have Docker set up as a server, create one and name itDocker
. - For Configuration files, add both the
docker-compose.yml
anddocker-compose.dev.yml
files from your project directory. - For Service, select
phpfpm
, then click OK. - Name this CLI Interpreter
phpfpm
, then click OK again.
- Create a new interpreter from the
Path mappings
- Add the following path mappings (
Local Path
->Remote Path
):/var/www/html
-><path_to_project>/src
/var/www/html/app/code/Magento/DataServices
-><path_to_project>/extensions/data-services/DataServices
/var/www/html/app/code/Magento/DataServicesMultishipping
-><path_to_project>/extensions/data-services/DataServicesMultishipping
/var/www/html/app/code/Magento/ServicesId
-><path_to_project>/extensions/services-id/ServicesId
/var/www/html/app/code/Magento/ServicesIdGraphQlServer
-><path_to_project>/extensions/services-id/ServicesIdGraphQlServer
/var/www/html/app/code/Magento/ServicesConnector
-><path_to_project>/extensions/services-connector/ServicesConnector
/var/www/html/app/code/Magento/ProductRecommendations
-><path_to_project>/extensions/product-recommendations/ProductRecommendations
/var/www/html/app/code/Magento/ProductRecommendationsLayout
-><path_to_project>/extensions/product-recommendations/ProductRecommendationsLayout
/var/www/html/app/code/Magento/PageBuilderProductRecommendations
-><path_to_project>/extensions/product-recommendations/PageBuilderProductRecommendations
/var/www/html/app/code/Magento/VisualProductRecommendations
-><path_to_project>/extensions/product-recommendations/VisualProductRecommendations
/var/www/html/app/code/Magento/ProductRecommendationsAdmin
-><path_to_project>/extensions/product-recommendations-admin/ProductRecommendationsAdmin
/var/www/html/app/code/Magento/ProductRecommendationsSyncAdmin
-><path_to_project>/extensions/product-recommendations-admin/ProductRecommendationsSyncAdmin
/var/www/html/app/code/Magento/CatalogSyncAdmin
-><path_to_project>/extensions/catalog-sync-admin/CatalogSyncAdmin
/var/www/html/app/code/Magento/BundleProductDataExporter
-><path_to_project>/extensions/commerce-data-export/BundleProductDataExporter
/var/www/html/app/code/Magento/CatalogDataExporter
-><path_to_project>/extensions/commerce-data-export/CatalogDataExporter
/var/www/html/app/code/Magento/CatalogInventoryDataExporter
-><path_to_project>/extensions/commerce-data-export/CatalogInventoryDataExporter
/var/www/html/app/code/Magento/CatalogUrlRewriteDataExporter
-><path_to_project>/extensions/commerce-data-export/CatalogUrlRewriteDataExporter
/var/www/html/app/code/Magento/ConfigurableProductDataExporter
-><path_to_project>/extensions/commerce-data-export/ConfigurableProductDataExporter
/var/www/html/app/code/Magento/DataExporter
-><path_to_project>/extensions/commerce-data-export/DataExporter
/var/www/html/app/code/Magento/QueryXml
-><path_to_project>/extensions/commerce-data-export/QueryXml
/var/www/html/app/code/Magento/ParentProductDataExporter
-><path_to_project>/extensions/commerce-data-export/ParentProductDataExporter
/var/www/html/app/code/Magento/ProductVariantDataExporter
-><path_to_project>/extensions/commerce-data-export/ProductVariantDataExporter
/var/www/html/app/code/Magento/ProductOverrideDataExporter
-><path_to_project>/extensions/commerce-data-export-ee/ProductOverrideDataExporter
/var/www/html/app/code/Magento/SaaSCatalog
-><path_to_project>/extensions/saas-export/SaaSCatalog
/var/www/html/app/code/Magento/SaaSCommon
-><path_to_project>/extensions/saas-exportSaaSCommon
/var/www/html/app/code/Magento/LiveSearch
-><path_to_project>/extensions/magento-live-search/LiveSearch
/var/www/html/app/code/Magento/LiveSearchAdapter
-><path_to_project>/extensions/magento-live-search/LiveSearchAdapter
/var/www/html/app/code/Magento/LiveSearchMetrics
-><path_to_project>/extensions/magento-live-search/LiveSearchMetrics
/var/www/html/app/code/Magento/LiveSearchStorefrontPopover
-><path_to_project>/extensions/magento-live-search/LiveSearchStorefrontPopover
/var/www/html/app/code/Magento/LiveSearchTerms
-><path_to_project>/extensions/magento-live-search/LiveSearchTerms
/var/www/html/app/code/Magento/GraphQlServer
-><path_to_project>/extensions/data-solutions-magento-bff/GraphQlServer
/var/www/html/app/code/Magento/AdminGraphQlServer
-><path_to_project>/extensions/data-solutions-magento-bff/AdminGraphQlServer
/var/www/html/app/code/Magento/ExternalSchemaGraphQlServer
-><path_to_project>/extensions/data-solutions-magento-bff/ExternalSchemaGraphQlServer
- Add the following path mappings (
-
Open
PHPStorm > Preferences > Languages & Frameworks > PHP > Debug
and set Debug Port to9000,9003
. -
Open
PHPStorm > Preferences > Languages & Frameworks > PHP > DBGp Proxy
and set Port to9001
. -
Open
PHPStorm > Preferences > Languages & Frameworks > PHP > Servers
and create a new server:- Set Name and Host to your domain name (ex.
magento2.test
) - Keep port set to
80
- Check the Path Mappings box
- Add the following path mappings (to match the volume bindings from step 3c above):
./src
->/var/www/html
./extensions/data-services/DataServices
->/var/www/html/app/code/Magento/DataServices
./extensions/data-services/DataServicesMultishipping
->/var/www/html/app/code/Magento/DataServicesMultishipping
./extensions/services-id/ServicesId
->/var/www/html/app/code/Magento/ServicesId
./extensions/services-id/ServicesIdGraphQlServer
->/var/www/html/app/code/Magento/services-id/ServicesIdGraphQlServer
./extensions/services-connector/ServicesConnector
->/var/www/html/app/code/Magento/services-connector/ServicesConnector
./extensions/product-recommendations/ProductRecommendations
->/var/www/html/app/code/Magento/ProductRecommendations
./extensions/product-recommendations/ProductRecommendationsLayout
->/var/www/html/app/code/Magento/ProductRecommendationsLayout
./extensions/product-recommendations/PageBuilderProductRecommendations
->/var/www/html/app/code/Magento/PageBuilderProductRecommendations
./extensions/product-recommendations/VisualProductRecommendations
->/var/www/html/app/code/Magento/VisualProductRecommendations
./extensions/product-recommendations-admin/ProductRecommendationsAdmin
->/var/www/html/app/code/Magento/ProductRecommendationsAdmin
./extensions/product-recommendations-admin/ProductRecommendationsSyncAdmin
->/var/www/html/app/code/Magento/ProductRecommendationsSyncAdmin
./extensions/catalog-sync-admin/CatalogSyncAdmin
->/var/www/html/app/code/Magento/CatalogSyncAdmin
./extensions/commerce-data-export/app/code/Magento/BundleProductDataExporter
->/var/www/html/app/code/Magento/BundleProductDataExporter
./extensions/commerce-data-export/app/code/Magento/CatalogDataExporter
->/var/www/html/app/code/Magento/CatalogDataExporter
./extensions/commerce-data-export/app/code/Magento/CatalogInventoryDataExporter
->/var/www/html/app/code/Magento/CatalogInventoryDataExporter
./extensions/commerce-data-export/app/code/Magento/CatalogUrlRewriteDataExporter
->/var/www/html/app/code/Magento/CatalogUrlRewriteDataExporter
./extensions/commerce-data-export/app/code/Magento/ConfigurableProductDataExporter
->/var/www/html/app/code/Magento/ConfigurableProductDataExporter
./extensions/commerce-data-export/app/code/Magento/DataExporter
->/var/www/html/app/code/Magento/DataExporter
./extensions/commerce-data-export/app/code/Magento/ParentProductDataExporter
->/var/www/html/app/code/Magento/ParentProductDataExporter
./extensions/commerce-data-export/app/code/Magento/ProductVariantDataExporter
->/var/www/html/app/code/Magento/ProductVariantDataExporter
./extensions/commerce-data-export-ee/app/code/Magento/ProductOverrideDataExporter
->/var/www/html/app/code/Magento/ProductOverrideDataExporter
./extensions/saas-export/app/code/Magento/SaaSCatalog
->/var/www/html/app/code/Magento/SaaSCatalog
./extensions/saas-export/app/code/Magento/SaaSCommon
->/var/www/html/app/code/Magento/SaaSCommon
./extensions/magento-live-search/app/code/Magento/LiveSearch
->/var/www/html/app/code/Magento/LiveSearch
./extensions/magento-live-search/app/code/Magento/LiveSearchAdapter
->/var/www/html/app/code/Magento/LiveSearchAdapter
./extensions/magento-live-search/app/code/Magento/LiveSearchMetrics
->/var/www/html/app/code/Magento/LiveSearchMetrics
./extensions/magento-live-search/app/code/Magento/LiveSearchStorefrontPopover
->/var/www/html/app/code/Magento/LiveSearchStorefrontPopover
./extensions/magento-live-search/app/code/Magento/LiveSearchTerms
->/var/www/html/app/code/Magento/LiveSearchTerms
./extensions/data-solutions-magento-bff/GraphQlServer
->/var/www/html/app/code/Magento/GraphQlServer
./extensions/data-solutions-magento-bff/AdminGraphQlServer
->/var/www/html/app/code/Magento/AdminGraphQlServer
./extensions/data-solutions-magento-bff/ExternalSchemaGraphQlServer
->/var/www/html/app/code/Magento/ExternalSchemaGraphQlServer
- Set Name and Host to your domain name (ex.
-
Go to
Run > Edit Configurations
and create a newPHP Remote Debug
configuration by clicking the plus sign and selecting it. Set the Name to your domain (ex.magento2.test
). Check theFilter debug connection by IDE key
checkbox, select the server you just setup, and under IDE Key enterPHPSTORM
. This IDE Key should match the IDE Key set by the Chrome Xdebug Helper. Then click OK to finish setting up the remote debugger in PHPStorm. -
Open up
src/pub/index.php
, and set a breakpoint near the end of the file. Go toRun > Debug 'magento2.test'
, and open up a web browser. Ensure the Chrome Xdebug helper is enabled by clicking on it > Debug. Navigate to your Magento store URL, and Xdebug within PHPStorm should now trigger the debugger and pause at the toggled breakpoint.
Since version 40.0.0
, this project supports connecting to Docker with SSH/SFTP. This means that if you solely use either PhpStorm or VSCode, you no longer need to selectively mount host volumes in order to gain bi-directional sync capabilities from host to container. This will enable full speed in the native filesystem, as all files will be stored directly in the appdata
container volume, rather than being synced from the host. This is especially useful if you'd like to sync larger directories such as generated
, pub
& vendor
.
Copy docker-compose.dev-ssh.yml
to docker-compose.dev.yml
before installing Magento to take advantage of this setup. Then, create an SFTP connection at Preferences -> Build, Execution, Deployment -> Deployment. Connect to localhost
and use app
for the username & password. You can set additional options for working with Magento in PhpStorm at Preferences -> Build, Execution, Deployment -> Deployment -> Options.
Note that you must use your IDE's SSH/SFTP functionality, otherwise changes will not be synced. To re-sync your host environment at any time, run:
bin/copyfromcontainer --all
Running Docker on Linux should be pretty straight-forward. Note that you need to run some post install commands as well as installing Docker Compose before continuing. These steps are taken care of automatically with Docker Desktop, but not on Linux.
Copy docker-compose.dev-linux.yml
to docker-compose.dev.yml
before installing Magento to take advantage of this setup.
The host.docker.internal
hostname is used on Docker for Mac/Windows to reference the Docker daemon. On Linux, this hostname does not exist.
This hostname is hard-coded in the php.ini file. To make this hostname resolve, add "host.docker.internal:172.17.0.1"
to the app.extra_hosts
parameter of docker-compose.yml
, replacing 172.17.0.1
with the result of:
docker run --rm alpine ip route | awk 'NR==1 {print $3}'
You must also create a new entry in your /etc/hosts
file using the same IP:
172.17.0.1 host.docker.internal
To enable Xdebug on Linux, you may also need to open port 9003 on the firewall by running:
sudo iptables -A INPUT -p tcp --dport 9003 -j ACCEPT
You may also have to increase a virtual memory map count on the host system which is required by Elasticsearch.
Add the following line to the /etc/sysctl.conf
file on your host:
vm.max_map_count=262144
These docker images have built-in support for Blackfire.io. To use it, first register your server ID and token with the Blackfire agent:
bin/root blackfire-agent --register --server-id={YOUR_SERVER_ID} --server-token={YOUR_SERVER_TOKEN}
Next, open up the bin/start
helper script and uncomment the line:
#bin/root /etc/init.d/blackfire-agent start
Finally, restart the containers with bin/restart
. After doing so, everything is now configured and you can use a browser extension to profile your Magento store with Blackfire.
To work with MFTF you will need to first enable the selenium
image in the docker-compose.dev.yml
file. Then, you will need to run the following.
- Run mftf build process
bin/mftf build:project
. This should build the basic setup for mftf in your project. - Update the
extra_host
values to match your Magento URL and IP indocker-compose.dev.yml
. - Update the values in
src/dev/tests/acceptance/.env
, including adding the new lineSELENIUM_HOST=selenium
to define the host Codeception should connect to. - Run a sample test
bin/mftf run:test AdminLoginSuccessfulTest
. - Update your
nginx.conf
file to allow access to the dev section with the following, before the finaldeny all
section:
location ~* ^/dev/tests/acceptance/utils($|/) {
root $MAGE_ROOT;
location ~ ^/dev/tests/acceptance/utils/command.php {
fastcgi_pass fastcgi_backend;
fastcgi_index index.php;
fastcgi_param SCRIPT_FILENAME $document_root$fastcgi_script_name;
include fastcgi_params;
}
}