Skip to content

About

A single make command that bootstraps a fully configured Magento 2 development environment

Resources

Stars

1 star

Watchers

1 watching

Forks

Latest commit

 

History

12 Commits

Folders and files

NameName
Last commit message
Last commit date
 
 
 
 
 
 
 
 

Repository files navigation

Magento 2 + Warden Installer

A single make command that bootstraps a fully configured Magento 2 development environment using Warden.

Prerequisites

Tool Purpose
Warden Docker-based dev environment manager
Docker Desktop Container runtime
Magento Marketplace credentials Downloading Magento via Composer

Before running the installer, make sure your Magento Marketplace credentials are present in ~/.composer/auth.json:

{
    "http-basic": {
        "repo.magento.com": {
            "username": "<your-public-key>",
            "password": "<your-private-key>"
        }
    }
}

You can generate keys at commercemarketplace.adobe.com.

Warden must also be running before you start:

warden svc up

Usage

Quick start with npx (recommended)

The installer is published on npm as create-magento, so you do not need to clone this repository:

npx create-magento <domain> <magento-version> [KEY=VALUE ...]
npx create-magento app.examplemagento.test 2.4.8-p3
npx create-magento app.examplemagento.test 2.4.8-p3 SAMPLE_DATA=true HYVA_THEME=true

The project directory is created inside the directory you run the command from. Any KEY=VALUE argument is forwarded to make as a variable (see Variables).

Using the Makefile directly

make create-magento <domain> <magento-version> [KEY=VALUE ...]

Example

make create-magento app.examplemagento.test 2.4.8-p3

This creates a new project directory ./examplemagento/ relative to the Makefile, installs Magento 2.4.8-p3, and makes it available at https://app.examplemagento.test.

Domain convention

The domain argument follows the pattern app.<project-name>.test. The middle segment becomes the Warden environment name and the project directory name.

Argument Result
app.examplemagento.test env name: examplemagento, project dir: ./examplemagento/
app.myshop.test env name: myshop, project dir: ./myshop/

Variables

Override any variable directly on the command line:

Variable Default Description
PHP_VERSION 8.3 PHP version used inside the Warden container
SAMPLE_DATA false Set to true to install Magento sample data (Luma catalog)
HYVA_THEME false Set to true to install the open-source Hyvä theme and make it the active theme
# Use a different PHP version
make create-magento app.myshop.test 2.4.7-p5 PHP_VERSION=8.2

# Install sample data
make create-magento app.myshop.test 2.4.8-p3 SAMPLE_DATA=true

# Install sample data and the Hyvä theme
make create-magento app.myshop.test 2.4.8-p3 SAMPLE_DATA=true HYVA_THEME=true

What it does

Before the numbered steps begin, the installer runs a pre-flight validation: it checks that both arguments are provided, that warden is available in $PATH, and that the target project directory does not already exist.

The 10 numbered steps are:

1. Create project directory

Creates <project-name>/ next to the Makefile. All Magento files will live here.

2. Initialise Warden environment

  • Runs warden env-init with environment type magento2
  • Patches PHP_VERSION in the generated .env file
  • Signs a local TLS certificate for <project-name>.test
  • Reloads Traefik so it serves the new certificate (Warden's sign-certificate is supposed to do this itself but its check fails silently)

3. Start Warden environment

  • Brings up all Docker services (PHP-FPM, Nginx, MySQL, Redis, OpenSearch, RabbitMQ, Varnish)
  • Waits 10 seconds for Mutagen file sync to initialise

4. Install Magento via Composer

Downloads magento/project-community-edition at the requested version from repo.magento.com and installs it into the container webroot.

5. Run Magento setup:install

Installs Magento with the following service configuration:

Service Host Notes
Database db database: magento, user: magento
OpenSearch opensearch:9200 index prefix: magento2
Redis (sessions) redis:6379 db: 2
Redis (cache) redis:6379 db: 0
Redis (full-page cache) redis:6379 db: 1
RabbitMQ rabbitmq:5672 user: guest
Varnish varnish:80 full-page cache

6. Apply environment configuration

Locks the following settings via --lock-env (they cannot be changed from the admin panel):

Config path Value Purpose
web/secure/offloader_header X-Forwarded-Proto SSL termination via Varnish/Traefik
web/secure/use_in_frontend 1 Force HTTPS on storefront
web/secure/use_in_adminhtml 1 Force HTTPS on admin
web/seo/use_rewrites 1 Enable URL rewrites
system/full_page_cache/caching_application 2 Use Varnish for full-page cache
system/full_page_cache/ttl 604800 FPC TTL: 7 days
catalog/search/enable_eav_indexer 1 Enable EAV indexer for search

7. Enable developer mode

Sets Magento to developer mode so errors are shown and static content is generated on the fly.

8. Disable extra modules

Disables two modules that are not needed in a local development environment:

Module Why disabled
Magento_TwoFactorAuth 2FA on the admin login blocks access during local development
Magento_AdminAdobeImsTwoFactorAuth Adobe IMS-based 2FA, also blocks admin access locally

9. Install sample data (optional)

Only runs when SAMPLE_DATA=true is passed; otherwise the step is skipped. It installs the Luma demo catalog:

  1. bin/magento sampledata:deploy downloads the sample data packages via Composer (uses the same Marketplace keys)
  2. bin/magento setup:upgrade enables the sample data modules and imports products, categories, CMS pages and customers
  3. bin/magento indexer:reindex and bin/magento cache:flush

This adds several minutes to the installation.

10. Install Hyvä theme (optional)

Only runs when HYVA_THEME=true is passed; otherwise the step is skipped. It installs the open-source Hyvä theme (OSL 3.0 / AFL 3.0 since 1.4.0) and makes it the active storefront theme:

  1. Registers the Hyvä GitHub repositories in composer.json as git repositories, as documented in the Hyvä default theme README. No Hyvä account or key is needed.
  2. composer require hyva-themes/magento2-default-theme
  3. bin/magento setup:upgrade, which also registers the theme in the database
  4. Disables the legacy customer captcha (customer/captcha/enable 0), which Hyvä does not support
  5. Sets design/theme/theme_id to the Hyva/default theme and flushes the cache

Works together with SAMPLE_DATA=true: the Luma sample catalog is then rendered with Hyvä.

Credentials

Value
Admin URL https://app.<project-name>.test/admin
Admin user admin
Admin password password1
Database host db, name magento, user magento, password magento

Troubleshooting

warden is not installed or not found in PATH Install Warden from docs.warden.dev/installing.html and make sure warden svc up has been run.

directory already exists The project directory from a previous run is still there. Remove it and try again:

cd examplemagento && warden env down && cd .. && rm -rf examplemagento

Composer authentication error Your Magento Marketplace keys are missing or wrong. Check ~/.composer/auth.json and verify the keys at commercemarketplace.adobe.com.

Browser shows a warden.test certificate instead of <project-name>.test Traefik did not load the project certificate. Reload it with:

warden svc up traefik && warden svc restart traefik

The installer does this automatically since version 1.2.0.

Certificate not trusted in browser Run warden trust-ca once to add Warden's root CA to your system trust store.

About

A single make command that bootstraps a fully configured Magento 2 development environment

Resources

Stars

1 star

Watchers

1 watching

Forks

Releases

Packages

Contributors

Languages