Repository files navigation

• What You get
• How to install
  • Requirements
  • Installation steps
  • Default credentials and settings
  • Getting updates and fixes
• Day-to-day development scenarios
  • Access Magento
  • Reinstall Magento
  • Clear Magento cache
  • Switch between CE and EE
  • Sample data installation
  • Basic data generation
  • Use Magento CLI (bin/magento)
  • Debugging with XDebug
  • Connecting to MySQL DB
  • View emails sent by Magento
  • Accessing PHP and other config files
  • Upgrading Magento
  • Multiple Magento instances
  • Update Composer dependencies
  • Running Magento tests
• Environment configuration
  • Switch between PHP versions
  • Activating Varnish
  • Activating ElasticSearch
  • Redis for caching
  • Reset environment
  • Switch NodeJS Versions
• DevBox tests
• FAQ

⚠️ This project is under development and may become official Magento DevBox in the future. There is also aDevBox for Magento Cloud.

It's expected that the Magento 2 project source code will be located and managed on the host to allow quick indexing of project files by IDE. All other infrastructure is deployed in kubernetes cluster on Minikube.

Current DevBox aims to support multi-service multi-instance deployment in one click. Multiple Magento projects should be installed in a single Kubernetes cluster and share resoruces. Each of the Magento projects may be deployed as a monolith or a set of services. The DevBox is optimized for development scenarios using local environment.

The environment also suitable for for Magento Commerce and Magento B2B development.

Theproject initialization script configures a complete development environment:

1. Configures all software necessary for Magento 2: Nginx, PHP 7.x, MySQL 5.6, Git, Composer, XDebug, Redis, Rabbit MQ, Varnish
2. Installs Magento 2 from Git repositories or Composer packages (can be configured viacheckout_source_from option inetc/instance/config.yaml)

If you never used Kubernetes before, read theKubernetes Docs first.

The software listed below should be available inPATH (except for PHP Storm).

• Docker
• Minikube
• Helm
• VirtualBox
• Git - Ensure that SSH keys are generated and associated with your Github account. Seehow to check andhow to configure, if not configured.
  ℹ️ To obtain the codebase without cloning, just use the Magento 2 codebase instead ofdevbox-magento/magento2ce. Either method will produce a successful installation.
  

• PHP Storm, optional but recommended. To get Helm support in PhpStorm make sure to get v2018.3+
• NFS server must be installed and running on *nix and OSX hosts; usually available, followinstallation steps first

ℹ️ In case of any issues during installation, please readFAQ section

1. Open terminal and change your directory to the one you want to contain Magento project.

2. Download or clone the project with DevBox configuration:

   ⚠️ Do not open it in PhpStorm untilinit_project.sh has completed PhpStorm configuration in the initialize project step below.

   git clone --recursive git@github.com:magento/magento2-kubernetes-devbox.git magento2-devbox

   Optionally, if you use private repositories on GitHub or download packages from the Magento Marketplace using Composer.

   1. Copyetc/composer/auth.json.dist toetc/composer/auth.json.
   2. Specify your GitHub token by adding"github.com": "your-github-token" to thegithub-oauth section for GitHub authorization.
   3. Add the Magento Marketplace keys for Marketplace authorization to therepo.magento.com section.
   4. Copy (optional)etc/instance/config.yaml.dist asetc/instance/<instance_name>.yaml and make the necessary customizations. Instance name is Magento instance identifier that can only include letters and numbers.
   5. Copy (optional)etc/env/config.yaml.dist asetc/env/config.yaml and make the necessary customizations.

3. Initialize the project (this will configure the environment, install Magento):

   cd magento2-devbox# NFS configuration is needed just once for each project, it will prompt for your password to make changes on the hostbash scripts/host/configure_nfs_exports.shbash init_project.sh

4. Use themagento2-devbox directory as the project root in PHP Storm (notmagento2-devbox/magento). This is important, because in this case PHP Storm will be configured automatically byinit_project.sh.

5. Configure the remote PHP interpreter in PHP Storm. Go to Preferences, then Languages and Frameworks. Click PHP and add a new remote interpreter. Select Deployment configuration as a source for connection details.

Some of default settings are available for override. These settings can be found in theetc/instance/config.yaml.dist andetc/env/config.yaml.dist.

To override settings create a copy ofetc/env/config.yaml.dist under the name 'config.yaml' and add your custom settings.

You can create multiple copies ofetc/instance/config.yaml.dist, each of those copies will be responsible for a separate Magento instance deployed in the DevBox. Config file name must only include alpha-numeric characters and will be used to isolate instances (for instance domain name generation, DB name etc).

Upon a successful installation, you'll see the location and URL of the newly-installed Magento 2 application in console.

Web access:

• Access storefront athttp://magento.<instance_name> (can be found inetc/instance/<instance_name>.yaml)
• Access admin panel athttp://magento.<instance_name>/admin/
• Magento admin user/password:admin/123123q
• Rabbit MQ control panel: runbash k-open-rabbitmq, credentialsadmin/123123q

ℹ️ Your admin URL, storefront URL, and admin user and password are located inetc/instance/<instance_name>.yaml.

Codebase and DB access:

• Path to your Magento installation in the container is the same as on the host
• MySQL DB host:
  • inside the container:localhost
  • remotely: runminikube ip to get the IP and use port30306
• MySQL DB name:magento_<instance_name>,magento_<instance_name>_integration_tests
• MySQL DB user/password:root:123123q

Codebase on host

• CE codebase:magento2-devbox/<instance_name>
• Magento Commerce codebase will be available if path to commerce repository is specified inetc/instance/<instance_name>.yaml:magento2-devbox/<instance_name>/magento2ee

Current devbox project followssemantic versioning so feel free to pull the latest features and fixes, they will not break your project.For example your current branch is2.0, then it will be safe to pull any changes fromorigin/2.0. However branch3.0 will contain changes backward incompatible with2.0.Note, that semantic versioning is only used forx.0 branches (not fordevelop ormaster).

ℹ️ To apply changes runbash k-upgrade-environment.

Use the following command to open current instance:

./m-open

Hostname can also be found inmagento/host_name section ofetc/instance/<instance_name>.yaml.

Use commands described inSwitch between CE and EE section with-f flag. Before doing actual re-installation, these commands update linking of EE codebase, clear cache, update composer dependencies.

If no composer update and relinking of EE codebase is necessary, use the following command. It will clear Magento DB, Magento caches and reinstall Magento instance.

Go to the root of the project in command line and execute:

./m-reinstall

Go to the root of the project in command line and execute:

./m-clear-cache

Assume, that EE codebase is available inmagento2-devbox/magento/magento2ee.The following commands will link/unlink EE codebase, clear cache, update composer dependencies and reinstall Magento.Go to 'magento2-devbox' created earlier and run in command line:

./m-switch-to-ce# OR./m-switch-to-ee

Force switch can be done using-f flag even if already switched to the target edition. May be helpful to relink EE modules after switching between branches.

Upgrade can be performed instead of re-installation using-u flag.

To install Magento with sample data using Git:

1. Uncomment the sample data repository link atadditional_repositories inetc/instance/<instance_name>.yaml. To ensure the yaml file can be correctly parsed, only remove the# and the space afterwards.
2. Run./m-switch-to-ce -f or./m-switch-to-ee -f, depending on the edition to be installed. To disable sample data, comment out additional repositories and force-switch to necessary edition (using the same commands).

If sample data is not showing, try the following:

1. Navigate to themagento2-devbox/<instance_name> directory such asmagento2-devbox/default.
2. Rungit clone git@github.com:magento/magento2-sample-data.git orgit@github.com:magento/magento2-sample-data-ee.git depending on the edition to be installed.
3. Navigate back up to themagento2-devbox directory.
4. Run./m-switch-to-ce -f or./m-switch-to-ee -f, depending on the edition to be installed.

To install Magento with sample data using Composer:

Follow the steps outlinedhere.

Several entities are generated for testing purposes by default using REST API after Magento installation:

• Customer with address (credentialscustomer@example.com:123123qQ)
• Category
• Couple simple products
• Configurable product

To disable this feature, setmagento/generate_basic_data inetc/instance/<instance_name>.yaml to0 and run./m-switch-to-ce -f or./m-switch-to-ee -f, depending on the edition to be installed.

Go to 'magento2-devbox' created earlier and run in command line:

./m-bin-magento<command_name># e.g../m-bin-magento list

XDebug is already configured to connect to the host machine automatically. So just:

1. Set XDEBUG_SESSION=1 cookie (e.g. using 'easy Xdebug' extension for Firefox). SeeXDebug documentation for more details
2. Start listening for PHP Debug connections in PhpStorm on default 9000 port. See how tointegrate XDebug with PhpStorm
3. Set beakpoint or set option in PhpStorm menu 'Run -> Break at first line in PHP scripts'

Go to 'magento2-devbox' created earlier and run in command line:

bash k-ssh-mysql

After successful login to the container run the following command and enter123123q when prompted for a password:

mysql -uroot -p

To connect remotely runminikube ip to get the IP and use port30306

Not available yet.

The following configuration files are used by default:

• NGINX
• PHP-FPM:ini,conf
• xDebug
• Dockerfile for monolith base image
• Actually applied Dockerfile for monolith with customizations
• Actually applied Dockerfile for monolith with xDebug and customizations
• Kubernetes config for Monolith
• Kubernetes Helm variables

Sometimes it is necessary to test upgrade flow. This can be easily done as follows (assuming that you have installed instance):

• For git-based installation - check out codebase corresponding to the target Magento version. Or modify yourcomposer.json in case of composer-based installation
• Use commands described inSwitch between CE and EE section with-u flag

Not available yet.

Go to 'magento2-devbox' created earlier and run in command line:

./m-composer install# OR./m-composer update

Seehow to run Magento tests from PhpStorm using remote PHP in Kubernetes cluster

Not available yet.

Use the following commands to enable/disable varnish :m-varnish disable orm-varnish enable.

You can also setuse_varnish: 1 inetc/env/config.yaml to use varnish. Changes will be applied oninit_project.sh -f.

The VCL content can be found inconfigmap.yaml.

Setsearch_engine: "elasticsearch" inetc/env/config.yaml to use ElasticSearch as current search engine orsearch_engine: "mysql" to use MySQL. Changes will be applied onm-reinstall.

Use the following commands to switch between search engines without reinstalling Magento:m-search-engine elasticsearch orm-search-engine mysql.

Redis is configured as cache backend by default.

It is possible to reset project environment to default state, which you usually get just after project initialization. The following command will re-initialize Kubernetes cluster. Magento 2 code base (magento directory) andetc/instance/<instance_name>.yaml and PhpStorm settings will stay untouched.

Go to 'magento2-devbox' created earlier and run in command line:

./init_project.sh -f

It is possible to reset Magento 2 code base at the same time. Magento 2 code base will be deleted and then cloned from the repositories specified inetc/config.yaml

./init_project.sh -fc

To reset PhpStorm project configuration, in addition to-f specify-p option:

./init_project.sh -fp

Ultimate project reset can be achieved by combining all available flags:

./init_project.sh -fcp

NodeJS not available yet.

The tests are executed on every PR on Travis CI. It is possible to configure the same tests to run on the forked repository.In order to run composer-based Magento tests for the fork, repo.magento.com credentials must be set toCOMPOSER_AUTHenvironment variable on Travis CI, the variable value should be:

'{"http-basic": {"repo.magento.com": {"username": "<public_key>","password": "<secret_key>"}}}'

An extended testsuite by default is executed against the master branch only.It is possible to execute an extended testsuite on every build by commenting outif: branch = master in the.travis.yaml

The same tests can be run on local using the following command.⚠️ only one devbox can be running on the same host at the same time. The tests will destroy existing devbox installation.

cd testsbash ./<test-name>.sh

1. To debug any CLI script in current Devbox project, setdebug:devbox_project option inetc/env/config.yaml to1
2. Make sure that you usedmagento2-devbox directory as project root in PHP Storm (notmagento2-devbox/magento)
3. If project opened in PhpStorm looks broken, close PhpStorm and removemagento2-devbox/.idea. Run./magento2-devbox/scripts/host/configure_php_storm.sh. After opening project in PhpStorm again everything should look good
4. Please make sure that currently installed software, specified inrequirements section, meets minimum version requirement
5. Be careful if your OS is case-insensitive, NFS might break the symlinks if you cd into the wrong casing and you power the devbox up. Just be sure to cd in to the casing the directory was originally created as.
6. Cannot run unit tests from PHPStorm on Magento 2.2, see possible solutionhere
7. Permission denied (publickey)
8. If you getminikube time out error restarting cluster while initializing project, runminikube stop && minikube delete && ./init_project.sh.
9. To modify the docker image used for php-fpm container:
   • Make changes inetc/docker/monolith/Dockerfile
   • Run./k-upgrade-environment
   • Run./k-status to open kubernetes dashboard and delete Replica Set namedmagento2-monolith-*. The container should be restarted and its Age should reset
10. If you faceInput/output error command terminated with exit code 1 try to run the same command again, it will succeed after several trials.
11. The project was working initially, but Magento instance domain name stopped resolving. In some cases minikube IP may be changed, run./scripts/host/configure_etc_hosts.sh