aligent/magento2-local repository overview

⁠Docker Compose Setup for Adobe Commerce

⁠Version Support

This repository now supports multiple Magento and PHP versions through a unified build system. You can easily switch between versions using environment variables without modifying compose files or Dockerfiles.

⁠Switching Versions

Set the MAGENTO_VERSION environment variable to use a different version.

All service versions can be customised via environment variables:

• MAGENTO_VERSION - PHP container version (required)
• MARIADB_VERSION - Database version (default: 10.6)
• OPENSEARCH_VERSION - Search engine version (default: 2.12.0)
• RABBITMQ_VERSION - Message queue version (default: 3.12)
• VALKEY_VERSION - Cache/session storage version (default: 8.1)
• MAILPIT_VERSION - Email testing tool version (default: 1.10)
• COMPOSE_PROFILES - Enable optional services (see below)

This is all handled automatically through the autogenerated .env file that manta creates. However by modifying this env file you can easily change the version of services without setting up a new project.

⁠GraphQL Service

The GraphQL service is only available for Magento 2.4.7 and above as earlier versions do not support GraphQL Inspector properly.

To enable the GraphQL service, add graphql to the COMPOSE_PROFILES environment variable. When using this you must also have NGINX_CONFIG=no-graphql set (or an equivalent custom configuration that disables the graphql upstream server).

⁠Using Manta

⁠Guided Setup (Recommended!)

manta init <directory_name>

Manta will prompt you for your platform and project and execute the init process automatically.

⁠Using docker compose

It is possible to use the template without the manta cli

⁠Creating a new project

1. Create a .env file based on the .env.example.

2. Clone the application repository to the src/ directory

3. git clone [email protected]:aligent/mcloud-partner.git src

4. Bring all services up using docker compose up -d

5. Install composer packages using docker compose exec php composer install

6. Install composer packages using docker compose exec php bin/magento --version

⁠How it works

⁠Architecture Diagram

⁠Traefik

Traefik⁠ is an application proxy that we use to route all HTTP requests to the correct container. You can find more information about the Aligent specific Traefik service in it's repository⁠. Note that this is part of the Aligent Ubuntu image and should already be configured on your laptop.

The routing is based on the PROJECT environment variable with three HTTP services exposed:

• web: https://{PROJECT}.aligent.dev
• rabbitmq: https://rabbitmq-{PROJECT}.aligent.dev
• mailhog: https://mail-{PROJECT}.aligent.dev

Additionally, your local Traefik dashboard is accessible at https://traefik.aligent.dev⁠.

⁠DevOps Guide

⁠Building PHP Container Images

The PHP containers use a unified build system that supports multiple Magento and PHP versions from a single Dockerfile.

⁠Build Arguments

• DOCKER_TAG (required): The version tag in format X.Y.Z or X.Y.Z-SUFFIX
  • Examples: 2.4.8, 2.4.8-8.4, 2.4.7-8.2, 2.4.5-custom
  • This is defined in docker hub

⁠Version-Specific Configuration

The build system includes automatic configuration management that:

• Loads version-appropriate PHP and PHP-FPM configurations
• Removes conflicting configs for other versions
• Supports custom configuration suffixes

⁠Configuration Loading Order

PHP loads configuration files in alphabetical order. Later files override settings from earlier files:

1. 2.4.8.dev.ini - Magento version-specific (numbers come before letters)
2. 8.4.dev.ini - PHP version-specific
3. dev.ini - Generic base configuration
4. _custom.dev.ini - Custom suffix (underscore loads after alphanumerics)

Files with underscores in the name (like _custom.dev.ini or 2.4.8_custom.dev.ini) load last due to alphabetical ordering, giving them the highest priority for overriding settings

⁠Adding Version-Specific Configuration

Create files in docker/php/config/usr/local/etc/php/conf.d/ or docker/php/config/usr/local/etc/php-fpm.d/:

# Magento version-specific
docker/php/config/usr/local/etc/php/conf.d/2.4.8.dev.ini

# PHP version-specific
docker/php/config/usr/local/etc/php/conf.d/8.4.dev.ini

# Custom suffix (highest priority)
docker/php/config/usr/local/etc/php/conf.d/_performance.dev.ini

The load-version-config.sh script automatically manages which configs are active based on the DOCKER_TAG build argument.

⁠Adding Support for New Magento Versions

1. Update the magento_php_map in docker/php/docker-bake.hcl:

   locals {
     magento_php_map = {
       "2.4.9" = "8.4"  # Add new version
       "2.4.8" = "8.3"
       # ...
     }
   }
   

   Copy

2. Add any version-specific configuration files if needed

3. Update docker hub with a new tag

4. Trigger a rebuild in docker hub

Note: For Magento versions below 2.4.7, only build the php and debug targets. The graphql target requires Magento 2.4.7 or above. Use the extended-legacy group for older versions:

⁠Customise nginx behaviour

The nginx configuration can be customised via the NGINX_CONFIG environment variable, which selects a configuration file from docker/nginx/.

Built-in configurations:

• default - Full configuration with GraphQL Application Server support (default)
• no-graphql - Configuration without GraphQL upstream

Creating custom configurations:

1. Copy an existing configuration as a starting point:

   cp docker/nginx/default.conf docker/nginx/custom.conf
   

   Copy

2. Modify the configuration as needed

3. Set the environment variable in your .env file (you can add this to manta by following these [docs](#Environment variable overrides)):

   NGINX_CONFIG=custom
   

   Copy

4. Restart the web service:

   docker compose restart web
   

   Copy

⁠Customise opensearch behaviour

OpenSearch supports project-specific customisation through custom entrypoint scripts.

How it works:

The PROJECT_CODE environment variable determines which custom script to execute. The entrypoint looks for a script named {project_code}.sh (lowercase) in docker/opensearch/.

Creating a custom entrypoint:

1. Create a script in docker/opensearch/ named after your project code (lowercase):

   # For PROJECT_CODE=MYPROJECT, create:
   docker/opensearch/myproject.sh
   

   Copy

2. Script template:

   #!/bin/bash
   set -e
   
   # Custom logic goes here...
   
   # Must exec to original entrypoint
   exec /usr/share/opensearch/opensearch-docker-entrypoint.sh "$@"
   

   Copy

3. Make the script executable:

   chmod +x docker/opensearch/myproject.sh
   

   Copy

See docker/opensearch/cooldrive.sh for a complete example demonstrating plugin installation.