Cloud 2.01

Local Development Setup

Setting up and configuring local development environments for Commerce Cloud projects.

Exam Critical: Understanding local development environments for Commerce Cloud projects is essential for the AD0-E717 exam! Know the differences between LAMP/Vagrant and Docker setups, and understand environment-specific configuration.

Local Development Setup

mindmap root((Local Development)) Options LAMP Stack Valet+ Vagrant Docker ece-tools Docker Benefits Mirrors production Production mode testing Config replication magento.app.yaml Cloud Package Base Commerce included Additional tools Works with any system Pro Plan Specifics auto_increment_increment = 3 Three production nodes Never set primary keys

Local Development Options for Commerce Cloud

When developing a Magento Commerce Cloud project locally, you have several environment options:

Traditional Options

LAMP Stack: Traditional Linux, Apache, MySQL, PHP setup
Valet+: Lightweight development environment for Mac
Vagrant: Virtual machine-based development environment

Docker (Recommended)

Docker via ece-tools: Magento's official Docker environment
Custom Docker: Your own Docker configuration

Recommendation: Docker via ece-tools is quickly becoming the preferred method as it closely mirrors the production environment.

Why Docker is Preferred

Key Advantages

1. Mirrors Production Environment

Docker environments can be configured to closely replicate the actual cloud infrastructure where your code will run.

2. Production Mode Testing

Test your application in production mode locally:

./vendor/bin/ece-tools docker:build --mode="production"

This creates a read-only environment that helps identify:

Modules trying to write to protected directories
File permission issues
Static content deployment problems
Code generation issues

3. Configuration Replication

Docker intelligently replicates configuration from .magento.app.yaml:

PHP version and extensions
Service versions (MySQL, Redis, Elasticsearch)
Environment variables
Build and deploy hooks

Huge Benefit: Your local environment automatically matches your cloud configuration!

Commerce Cloud Composer Package

What's Included

The Cloud Composer meta-package includes:

Base Magento Commerce: Complete Commerce application
ece-tools: Cloud deployment and build tools
Cloud patches: Cloud-specific fixes and optimizations
Docker configuration: Pre-configured Docker setup

Development Freedom

Since the base Commerce application is present, you can use any development system:

Your own Vagrant configuration
Custom Docker setup
Traditional LAMP stack
Valet+ on Mac

Note: While you can use any system, Docker provides the most accurate replication of the cloud environment.

Docker via ece-tools

Setting Up Docker Environment

Basic Setup

# Build Docker environment
./vendor/bin/ece-tools docker:build

# Build with specific mode
./vendor/bin/ece-tools docker:build --mode="developer"
./vendor/bin/ece-tools docker:build --mode="production"

Development Mode

Writable filesystem
Developer tools enabled
Code generation on-the-fly
Error reporting enabled

Production Mode

Read-only filesystem (except var/ and pub/media/)
Compiled code required
Static content deployed
Mirrors actual production constraints

Use Case: Validate your code works in production before deployment!

Pro Plan Auto-Increment Configuration

Critical Pro Plan Consideration

auto_increment_increment = 3

Pro plans use a custom auto_increment_increment value of 3 instead of the default 1.

Why? Production environment has three database nodes running in a cluster.

How It Works

Node 1: IDs 1, 4, 7, 10, 13...
Node 2: IDs 2, 5, 8, 11, 14...
Node 3: IDs 3, 6, 9, 12, 15...

This prevents ID conflicts when multiple nodes write simultaneously.

Critical Rule

NEVER SET PRIMARY KEY VALUES MANUALLY!

Setting primary keys manually could cause:

ID overlap between nodes
Data inconsistency
Database integrity issues
Difficult-to-debug production problems

Impact on Development

When developing for Pro plans:

Always use auto-increment for primary keys
Never hardcode entity IDs
Test with auto_increment_increment=3 locally if possible
Be aware IDs won't be sequential (1,2,3...) in production

.magento.app.yaml Configuration

Environment Configuration File

The .magento.app.yaml file defines your cloud environment configuration:

Key Configurations

# Example .magento.app.yaml
name: mymagento
type: php:8.1

relationships:
    database: "mysql:mysql"
    redis: "redis:redis"
    elasticsearch: "elasticsearch:elasticsearch"

hooks:
    build: |
        set -e
        php ./vendor/bin/ece-tools run scenario/build/generate.xml
        php ./vendor/bin/ece-tools run scenario/build/transfer.xml
    deploy: |
        php ./vendor/bin/ece-tools run scenario/deploy.xml
    post_deploy: |
        php ./vendor/bin/ece-tools run scenario/post-deploy.xml

crons:
    cronrun:
        spec: "* * * * *"
        cmd: "php bin/magento cron:run"

Docker Integration

When using ece-tools docker:build, Docker reads this file and:

Sets up services (MySQL, Redis, Elasticsearch) with specified versions
Configures PHP version and extensions
Runs build, deploy, and post-deploy hooks
Sets up cron jobs

Best Practices

Do's

Use Docker via ece-tools for most accurate environment
Test in production mode before deploying
Keep .magento.app.yaml in sync with requirements
Use auto-increment for all primary keys
Test with auto_increment_increment=3 for Pro plans
Match service versions to production
Run build/deploy hooks locally to catch issues

Don'ts

Don't manually set primary key values
Don't skip production mode testing
Don't write to protected directories
Don't assume sequential IDs in Pro plans
Don't ignore .magento.app.yaml configuration
Don't use incompatible service versions
Don't develop without testing build hooks

Exam Tips

Key Points to Remember

Development options: LAMP, Valet+, Vagrant, or Docker (preferred)
Docker command: ./vendor/bin/ece-tools docker:build --mode="production"
Docker benefits: Mirrors production, replicates .magento.app.yaml, tests read-only mode
Cloud package: Includes base Commerce + ece-tools + patches + Docker config
Environment freedom: Can use any system (Vagrant, custom Docker, etc.)
Pro plan DB: auto_increment_increment = 3 (three production nodes)
Critical rule: NEVER manually set primary key values
Configuration file: .magento.app.yaml defines environment
Production mode: Read-only filesystem, helps catch directory write issues
Service matching: Docker replicates versions from .magento.app.yaml

Local Development Setup