aemdesign/dispatcher-sdk repository overview

⁠Dispatcher SDK

AEM Dispatcher SDK Docker image for linux/amd64 (also runs on Apple Silicon via Rosetta 2).

Please go to docs/README.html to find the documentation.

⁠Docker Images

Images are available on both registries:

• Docker Hub: aemdesign/dispatcher-sdk
• GitHub Container Registry: ghcr.io/aem-design/dispatcher-sdk

⁠Tags

• latest - Latest build from main branch
• main - Latest build from main branch
• 2.0.x - Version tags (pushed when git tags are created)

⁠Running

docker run -d --rm -v ${PWD}/src:/mnt/dev/src -p 8080:80 -e AEM_PORT=4503 -e AEM_HOST=host.docker.internal aemdesign/dispatcher-sdk:latest

⁠Environment Variables

• AEM_HOST - AEM instance hostname (default: host.docker.internal)
• AEM_PORT - AEM instance port (default: 4503)

⁠Development

⁠CI/CD Pipeline

The project uses GitHub Actions for continuous integration and deployment:

• Platform: Images are built for linux/amd64
• Apple Silicon support: Works seamlessly on M1/M2/M3/M4 Macs via Docker Desktop's Rosetta 2 emulation
• Automated testing: Validates image on ubuntu-latest runner
• Image analysis: Uses dive for Docker image layer analysis
• Dual registry push: Automatically pushes to Docker Hub and GitHub Container Registry
• Git tag versioning: Pushing a git tag (e.g., 2.0.188) automatically creates a corresponding Docker image tag

⁠Why amd64 Only?

Adobe's mod_dispatcher.so module is only available as a compiled x86_64 binary. ARM64 builds are not feasible without ARM64-compiled binaries from Adobe. The amd64 images work on Apple Silicon Macs via Rosetta 2 emulation in Docker Desktop.

⁠Running on Apple Silicon Macs (M1/M2/M3/M4)

This image is built for linux/amd64 architecture but runs seamlessly on Apple Silicon Macs through Rosetta 2 emulation in Docker Desktop.

⁠Prerequisites

1. Docker Desktop for Mac (version 4.25.0 or later recommended)

   • Download from: https://www.docker.com/products/docker-desktop⁠

2. Rosetta 2 (usually already installed on modern macOS)

   • To verify/install: softwareupdate --install-rosetta

⁠Enable Rosetta 2 in Docker Desktop

1. Open Docker Desktop
2. Go to Settings (⚙️ icon) → General
3. Enable "Use Rosetta for x86_64/amd64 emulation on Apple Silicon"
4. Click Apply & Restart

⁠Verify It's Working

# Pull and run the dispatcher image
docker pull aemdesign/dispatcher-sdk:latest
docker run --rm aemdesign/dispatcher-sdk:latest uname -m

# Expected output: x86_64 (running via Rosetta 2)

⁠Performance Notes

• Rosetta 2 emulation provides near-native performance for most workloads
• First container start may be slightly slower (Rosetta translation cache warmup)
• Subsequent starts are fast
• No code changes needed - everything works transparently

⁠Monitoring Pipeline Status

The get-action-logs.ps1 PowerShell script provides easy access to GitHub Actions workflow status and logs.

⁠Prerequisites

• GitHub CLI (gh) must be installed and authenticated
• Install: winget install --id GitHub.cli
• Authenticate: gh auth login

⁠Quick Start

# Check current commit's pipeline status (saves logs to logs/ folder by default)
.\get-action-logs.ps1

# Wait for pipeline to complete
.\get-action-logs.ps1 -WaitForCompletion

# Show logs in console
.\get-action-logs.ps1 -ShowLogs

# Force re-download logs
.\get-action-logs.ps1 -Force

⁠Advanced Options

# View specific run's logs
.\get-action-logs.ps1 -RunId 12345678 -ViewLogs

# Download logs as zip
.\get-action-logs.ps1 -RunId 12345678 -Download

# Watch running workflow in real-time
.\get-action-logs.ps1 -Watch

# List recent runs
.\get-action-logs.ps1 -Limit 10

# Filter by status
.\get-action-logs.ps1 -Status failure

# Filter by workflow
.\get-action-logs.ps1 -Workflow "build.yml"

# Disable auto-save
.\get-action-logs.ps1 -SaveLogs:$false

⁠Saved Logs

Logs are automatically saved to the logs/ folder with the following naming convention:

logs/run-{runId}-{commitSha}-{workflowName}-{conclusion}.log

Example: logs/run-18709640324-780320e-build-success.log

Note: The script automatically detects if logs have already been downloaded and skips re-downloading them. Use -Force to re-download existing logs.

See full script documentation: Get-Help .\get-action-logs.ps1 -Full

⁠Creating a New Release

To create a new version release:

# Tag the commit
git tag 2.0.188
git push origin 2.0.188

This will automatically:

1. Trigger the build workflow
2. Build multi-platform Docker images
3. Tag images as aemdesign/dispatcher-sdk:2.0.188
4. Push to both Docker Hub and GitHub Container Registry
5. Create a GitHub release

⁠License

See LICENSE⁠ file for details.