Shopware Dev Runtime

Runtime helpers for disposable Shopware development instances on Coolify.

The repository deliberately does not contain Shopware. The Coolify template continues to run any dockware/shopware:${SHOPWARE_VERSION} image and mounts these helper scripts from the tiny runtime image published by this repository.

Responsibilities

The runtime handles development plumbing only:

• create/use Dockware's SSH user
• keep an optional SSH password in sync
• configure the default Git identity
• provide Shopware CLI as the standard extension validation/build tool
• mirror public sales-channel domains onto the internal http://shop origin for authenticated-gateway-free browser smoke tests
• configure Shopware to trust forwarded client metadata only from the Coolify reverse proxy
• configure GitHub App credentials for HTTPS Git operations
• clone repositories listed in DEV_PLUGINS into custom/plugins
• leave existing Git working copies untouched on restart

The existing stock SSHPiper installation remains responsible for external SSH routing and public-key authentication.

The Playwright MCP browser service runs with --isolated, so agent sessions use temporary Chromium profiles instead of sharing one persistent profile. This avoids profile-lock conflicts between sequential or concurrent Codex sessions.

Runtime image

The GitHub workflow publishes:

ghcr.io/aggrosoft/shopware-dev-runtime:main

The image is only a carrier for the scripts. A short-lived runtime service copies them into a named volume that the Shopware container mounts read-only at /opt/aggro.

Coolify Compose

Use compose.coolify.example.yaml as the template.

Important: disable Escape special characters in labels for the Coolify service. SSHPiper relies on Coolify/Compose interpolating ${SERVICE_FQDN_SHOP}, ${COMPOSE_PROJECT_NAME}, and the shared SSH key variable in the labels.

Environment

Per Shopware instance:

Variable	Purpose
SHOPWARE_VERSION	Dockware/Shopware image tag
SSH_PASSWORD	Optional password login when no shared public-key variable is configured
DEV_PLUGINS	Optional multiline list of repositories with optional version/branch selectors
GIT_USER_NAME	Defaults to Aggrosoft Dev Server
GIT_USER_EMAIL	Defaults to dev-server@aggrosoft.de

Project-shared values:

GITHUB_APP_CLIENT_ID
GITHUB_APP_PRIVATE_KEY
SSH_AUTHORIZED_KEYS_B64

The GitHub private key remains a normal multiline PEM value in Coolify.

SSH

The existing stock SSHPiper Docker plugin is used unchanged.

SSH_AUTHORIZED_KEYS_B64 contains the Base64 representation of a normal OpenSSH authorized_keys list. It is referenced only from SSHPiper labels and is not copied into the Shopware container.

When SSH_AUTHORIZED_KEYS_B64 is set, the stock SSHPiper Docker plugin uses its public-key Docker-exec bridge. When it is empty, password authentication is forwarded to Dockware's SSH server.

Because the stock Docker plugin switches authentication mode when sshpiper.authorized_keys is present, password and public-key authentication are not offered simultaneously for the same container. With the shared project variable configured, Shopware DEV instances effectively use public-key access.

Example source text before Base64 encoding:

ssh-ed25519 AAAA... developer-one
ssh-ed25519 AAAA... developer-two

Generate the single-line project value with:

printf '%s\n' 'ssh-ed25519 AAAA... developer-one' 'ssh-ed25519 AAAA... developer-two' | openssl base64 -A

To change the developer keys, update only the project-shared SSH_AUTHORIZED_KEYS_B64 value.

GitHub App references

Each Coolify resource should reference the project-shared GitHub values:

GITHUB_APP_CLIENT_ID={{project.GITHUB_APP_CLIENT_ID}}
GITHUB_APP_PRIVATE_KEY={{project.GITHUB_APP_PRIVATE_KEY}}
SSH_AUTHORIZED_KEYS_B64={{project.SSH_AUTHORIZED_KEYS_B64}}

Mark GITHUB_APP_PRIVATE_KEY as multiline on both the shared variable and the resource variable.

The runtime resolves the GitHub App installation dynamically for each repository in DEV_PLUGINS. The same app can therefore clone repositories from multiple organizations without configuring installation IDs. The app must be installed on each repository owner account and granted access to the repository.

DEV_PLUGINS is multiline. Each line supports one of these forms:

# Repository default branch
aggrosoft/shopware-firewall

# Highest stable Git tag matching a Composer version constraint
aggrosoft/shopware-cms-extras@4.x
aggrosoft/another-plugin@^2.3

# Explicit Git branch
aggrosoft/legacy-plugin@branch:6.6
aggrosoft/test-plugin@branch:feature/foo

Version selectors are resolved from remote Git tags with Composer's Semver implementation. Tags with a leading v are supported. Pre-release tags are ignored, and provisioning fails if no stable tag matches the requested constraint. There is no fallback to the default branch.

The runtime clones missing repositories only. It never automatically pulls, resets, checks out or deletes an existing Git checkout, even when the configured selector later changes.

Persistent remote development state

The Coolify template persists VS Code Remote and Codex state across container recreates:

• vscode_server:/var/www/.vscode-server
• codex_home:/var/www/.codex

This keeps installed remote VS Code extensions and Codex authentication/configuration when the Shopware container is recreated.