README

High-performance deployment CLI for Magento 2. Smart change detection, parallel static content deployment, dependency-aware theme compilation, and zero-downtime capabilities.

Why

Deploying Magento 2 is notoriously painful. Every existing option has significant trade-offs:

Custom deploy.sh scripts (most common) — run everything every time, full maintenance mode for 60-90 seconds, no rollback, no error recovery. Works until it doesn't.

Deployer — powerful PHP deployment tool, but requires writing deploy.php + hosts.yml, manually hardcoding themes and locales (no auto-detection), and runs the full pipeline every deploy regardless of what changed. Zero-downtime needs artifact mode with a separate build host. Multiple competing community recipes (jalogut, swiftotter) signal gaps people keep working around.

ece-tools (Adobe Commerce Cloud) — the most complete Magento deployment automation, but completely unusable outside Adobe Cloud. Hard dependency on Adobe's managed infrastructure. 4 config files, proprietary build containers. Useful only as a reference.

Capistrano — real atomic symlink deployments, but requires Ruby on your deploy machine. No change detection. Full rebuild every time.

The gap every tool misses: change detection. You changed one CSS file? Every tool above still runs di:compile (30-40s) + full SCD for all themes (20-30s). That's the 70+ seconds you wait for nothing.

nola-deploy fills this gap:

• One command install — composer require, no Ruby, no separate servers, no YAML manifests
• Auto-detects everything — queries your database for stores, themes, locales (Magento scope fallback)
• Skips what didn't change — theme-only change? Skip di:compile. PHP-only? Skip SCD.
• Zero DevOps overhead — no deploy recipes to write, no host configs, no build servers
• Works with or without git — hash-based fallback for teams that edit files directly

Benchmark

Tested on Magento 2.4.7 with Luma theme, PHP 8.3.

The more themes, locales, and modules you have, the bigger the improvement.

How It Works

vendor/bin/nola-deploy init     ← auto-detect stores, themes, locales from DB
vendor/bin/nola-deploy deploy   ← smart incremental deploy

1. Change detection — compares git diff + file hashes against last deploy manifest
2. Surgical compilation — PHP change? Regenerate only affected generated files. JS change? Copy to pub/static. Template change? Clear cache. No unnecessary full rebuilds.
3. Parallel SCD — deploys themes in parallel, respecting parent→child dependency order
4. Dependency-aware — Magento/blank deploys before Magento/luma (parent first)
5. Vendor tracking — composer require a new module? composer.lock change triggers full rebuild automatically

Quick Start

1. Setup

composer require nola/deploy
vendor/bin/nola-deploy init

init checks your environment (PHP, DB, extensions, disk space), auto-detects stores/themes/locales from the database, and generates .nola-deploy.yaml in your Magento root.

▸ Checking environment
    [OK] PHP 8.3.22
    [OK] bin/magento
    [OK] app/etc/env.php
    [OK] app/etc/config.php
    [OK] PHP extensions (6 required)
    [OK] Database connection
    [OK] Disk space (271.2 GB free)
    [OK] Composer vendor

▸ Detecting store configuration
  Found 1 store view(s) + admin
    default: Magento/luma [en_US]
    admin: Magento/backend [en_US]

  ✓ Config written to: .nola-deploy.yaml

Review .nola-deploy.yaml and adjust if needed — it's fully commented.

2. Deploy (recommended daily command)

vendor/bin/nola-deploy deploy

This is the only command you need for day-to-day deployments. It automatically detects what changed and runs only what's necessary — if nothing changed, it finishes in ~1 second.

When to use other commands

# First time deploying, or need a clean slate (clears generated/, pub/static/)
vendor/bin/nola-deploy deploy:fresh

# Preview what changed without deploying
vendor/bin/nola-deploy deploy:diff

If you haven't run init yet, deploy commands will remind you:

⚠ No .nola-deploy.yaml found.

  Run this first to set up your deployment config:

    vendor/bin/nola-deploy init

Commands

Common Options

# Force full rebuild (ignore change detection)
vendor/bin/nola-deploy deploy --force

# Enable maintenance mode with custom page during deploy
vendor/bin/nola-deploy deploy -m

# Preview without executing
vendor/bin/nola-deploy deploy --dry-run

# Override parallel workers
vendor/bin/nola-deploy deploy -j 8

# Deploy specific themes only
vendor/bin/nola-deploy deploy --themes=Vendor/mytheme

# Deploy specific locales only
vendor/bin/nola-deploy deploy --locales=en_US,fr_FR

Configuration

.nola-deploy.yaml

The config file lives in your Magento root. Generate it with init, then customize as needed.

Store Mapping

The most important section. Defines what themes and locales to deploy per store view. Auto-detected from your database with Magento scope fallback (store → website → default).

stores:
  default:
    theme: Magento/luma
    locales:
      - en_US
  french_store:
    theme: Vendor/custom-theme
    locales:
      - fr_FR
      - fr_BE
  admin:
    theme: Magento/backend
    locales:
      - en_US

Cache Control

# Flush everything (default)
cache:
  flush_all: true

# Or flush specific types only
cache:
  flush_all: false
  types:
    - config
    - layout
    - block_html
    - full_page

Custom Maintenance Page

maintenance:
  page: nola-deploy-maintenance.html

Create a single HTML file at that path (relative to Magento root). When you deploy with -m:

1. Your HTML becomes the maintenance page automatically
2. Magento maintenance mode is enabled
3. Deployment runs
4. Maintenance mode is disabled, original page restored

If the file doesn't exist, a clean built-in template is used.

Post-Deploy Commands

post_deploy:
  - bin/magento indexer:reindex
  - curl -s https://hooks.slack.com/... -d '{"text":"Deploy complete"}'

Shell commands that run from Magento root after deployment completes. Each command runs independently — one failure doesn't block the rest.

Static Content Strategy

static_content:
  strategy: quick      # quick | standard | compact
  parallel_jobs: 4     # number of parallel SCD workers
  use_node_less: true  # use Node.js LESS compiler (faster)

DI Compilation

di_compile:
  enabled: true
  cache: true        # cache compiled DI for incremental builds
  gc_disable: true   # disable PHP GC during compile (~30% faster)

Change Detection

nola-deploy tracks what changed since the last deploy and only runs what's needed.

Git-based (preferred)

When running in a git repository:

• Diffs committed changes since last deploy (git diff <last-commit>..HEAD)
• Includes uncommitted modifications (staged + unstaged)
• Includes untracked new files in app/code, app/design, app/etc
• Detects composer.lock changes (new modules installed via composer require)

Hash-based (fallback)

When git is not available (direct file edits, no repo):

• SHA-256 hashes of: composer.lock, config.php, vendor/composer/installed.json
• Directory hashes for app/code and app/design
• Compared against stored hashes from last deploy

What Gets Skipped

setup:upgrade Detection

nola-deploy automatically runs setup:upgrade --keep-generated when it detects changes to:

• db_schema.xml / db_schema_whitelist.json — declarative schema
• Setup/Patch/Data/ or Setup/Patch/Schema/ — data and schema patches
• Setup/UpgradeSchema.php, Setup/UpgradeData.php — legacy upgrade scripts
• Setup/InstallSchema.php, Setup/InstallData.php — legacy install scripts
• Setup/Recurring.php — recurring setup scripts
• etc/module.xml — module version changes
• composer.lock — new modules installed via composer require

The --keep-generated flag ensures previously compiled DI code is preserved, so di:compile runs on top of existing generated code rather than starting from scratch.

Surgical Deployment

nola-deploy goes beyond just skipping steps — it handles each file type at the granular level:

Vendor Changes

When you composer require a new module or update an existing one, composer.lock changes. nola-deploy detects this and triggers a full rebuild — setup:upgrade + di:compile + SCD for all themes. The vendor/ directory itself is not tracked (it's gitignored) — composer.lock is the reliable signal.

For the hash-based fallback (no git), vendor/composer/installed.json is also checked.

File Structure

magento-root/
├── .nola-deploy.yaml              ← your config (generated by init)
├── nola-deploy-maintenance.html   ← custom maintenance page (optional)
├── var/nola-deploy/
│   └── manifest.json              ← deploy history + hashes (auto-managed)
└── vendor/nola/deploy/            ← the package (via composer)
    ├── bin/nola-deploy
    ├── config/nola-deploy.yaml.dist
    ├── src/
    └── templates/maintenance.html

Requirements

• PHP 8.1+
• Magento 2.4.x
• Required PHP extensions: pdo_mysql, intl, mbstring, json, dom, simplexml

Development

git clone git@github.com:mrloc2015/nola-deploy.git
cd nola-deploy
composer install
vendor/bin/phpunit

License

MIT