README

Key Agency's shared Deployer 8 recipes: a base key recipe (Slack notifications + healthcheck) and per-platform wrappers with build and content-sync tasks.

Install

composer require --dev keyagency/deployer-recipes

Supported platforms

Each platform has its own section below with everything you need: the require, the tasks and the configuration.

Is your platform not listed? See Adding a platform.

All platforms

Every wrapper loads Deployer's base recipe for that platform plus the shared key recipe. In your project's deploy.php, require the wrapper for your platform and define your host:

namespace Deployer;

require 'vendor/keyagency/deployer-recipes/recipe/key/<platform>.php';

host('production')->set('deploy_path', '/var/www/example');

The shared key recipe registers on every platform:

• key:notify:start / key:notify:success / key:notify:failure — Slack messages, wired into the deploy flow (before deploy, after deploy:success, after deploy:failed).
• key:healthcheck — runs after deploy:success and fails the deploy if the HTTP status of key_healthcheck_url does not match key_healthcheck_expected_status.

It also runs deploy:unlock after deploy:failed, so a failed deploy never leaves the release locked.

To enable Slack notifications, add the webhook to your project's .env (picked up automatically — no webhook means no notifications):

KEY_SLACK_WEBHOOK=https://hooks.slack.com/services/...

A real environment variable KEY_SLACK_WEBHOOK (e.g. in CI) takes precedence over the .env file, and an explicit set('key_slack_webhook', ...) in deploy.php wins over both.

No webhook URL is bundled in this package. Each project supplies its own, so installing the package never posts to anyone else's Slack.

All custom config keys are prefixed with key_ to avoid collisions with Deployer's own options. The shared recipe also sets a few Deployer defaults: git_tty (true), writable_mode ('skip') and allow_anonymous_stats (false). Override them in your project's deploy.php when needed.

Shared configuration

How syncing works

Statamic and October CMS ship key:sync:* tasks that rsync content between the server and your machine. They are not wired into the deploy flow; call them directly, e.g. dep key:sync:content production.

• You are asked once for the direction (remote → local by default) and, when pushing to remote, for overwrite/delete confirmation.

• Every sync type has its own key_sync_<type> option holding a flat list of paths: a trailing slash marks a directory (which may mirror deletions and gets the optional backup), no trailing slash marks a single file (never deleted). Use Deployer's add() to append project-specific paths without redeclaring the defaults:

  add('key_sync_content', ['resources/navigation/']);

• Sources that do not exist are skipped, types without configured paths are skipped entirely, and a non-default SSH port on the host is respected.

• With key_sync_backup enabled, the destination directory is copied to <dir>-backup before each sync.

Sync configuration

Laravel

require 'vendor/keyagency/deployer-recipes/recipe/key/laravel.php';

Loads Deployer's laravel recipe plus the shared key recipe.

Tasks

• key:build:resources — builds the frontend locally (in a temporary git worktree, using the remote .env) and uploads public/build/ to the server. Wired into the deploy flow via after('deploy:vendors', 'key:build:resources'); override the deploy task to change or remove it.

Configuration

Statamic

require 'vendor/keyagency/deployer-recipes/recipe/key/statamic.php';

Loads Deployer's statamic recipe plus the shared key recipe, and shares public/assets and content between releases. The deploy task is overridden to drop statamic:stache:warm; statamic:stache:clear is kept so new content is picked up (the Stache lives in shared storage and the watcher is disabled in production), but the slow warming is skipped and the Stache rebuilds lazily on the next request, which avoids slow deploys on large sites. Make sure the watcher is disabled in production (STATAMIC_STACHE_WATCHER=auto).

Tasks

• key:build:resources — builds the frontend locally (in a temporary git worktree, using the remote .env) and uploads public/build/ to the server. Wired into the deploy flow via after('deploy:vendors', 'key:build:resources'); override the deploy task to change or remove it.
• key:sync:content / key:sync:assets / key:sync:forms / key:sync:addons — see How syncing works. key:sync:content can also include forms, addons and assets in one run. After each sync the Statamic stache is refreshed.

Configuration

October CMS

require 'vendor/keyagency/deployer-recipes/recipe/key/october.php';

Loads Deployer's laravel recipe (October CMS is built on Laravel) plus the shared key recipe. The deploy task is overridden to run the October CMS migrations (october:migrate) and mirror plugin and module assets into public/ (october:mirror) before publishing, and to write the deployed git revision to .version (system:update).

Tasks

• october:migrate / october:mirror — run artisan october:migrate and artisan october:mirror in the release. Part of the overridden deploy task.
• system:update — writes VERSION=<revision> to .version in the release, read from Deployer's REVISION file. Part of the deploy task.
• key:sync:theme / key:sync:storage — see How syncing works. theme syncs themes/<theme>/content/ and themes/<theme>/meta/ for every theme in key_october_themes; storage syncs storage/app/uploads/ and storage/app/media/. blocks.yaml is excluded by default. After each sync the October CMS cache is cleared.

To sync an extra theme, only the theme list needs to change:

set('key_october_themes', ['default', 'second-theme']);

Configuration

WordPress (Bedrock)

require 'vendor/keyagency/deployer-recipes/recipe/key/bedrock.php';

set('key_bedrock_theme', 'my-theme');

Loads Deployer's common recipe (with deploy:vendors in the deploy flow, since Bedrock is composer-based) plus the shared key recipe, and shares .env, web/.htaccess and web/app/uploads between releases.

Tasks

• key:build:resources — runs key_build_command locally in web/app/themes/<key_bedrock_theme> and uploads the build artifacts from key_build_uploads (default assets/js/ and style.css) to the same theme path on the server. Skips with a warning when key_bedrock_theme is not set.
• key:install:languages — downloads wp-cli.phar into the release and installs the core, plugin and theme languages for every language in key_languages.

Neither task is wired into the deploy flow; call them directly or wire them in your project's deploy.php:

after('deploy:vendors', 'key:build:resources');
before('deploy:publish', 'key:install:languages');

Configuration

Adding a platform

Create recipe/key/<platform>.php that requires the matching Deployer base recipe and the shared key recipe:

namespace Deployer;

require_once 'recipe/<platform>.php';

set('key_platform', '<PLATFORM>');

require_once __DIR__ . '/../key.php';

key_platform must be set before requiring key.php, so the task descriptions pick up the [<PLATFORM>] prefix.

Platform-specific features live in per-feature files under recipe/key/<platform>/ (e.g. recipe/key/october/sync.php), required by the wrapper. Sync features build on the shared helpers in recipe/helpers/sync.php: define a key_sync_<type> option per sync type (a flat list of paths) and register tasks that call key_sync_prompt() and key_sync().

About Key Agency

Key Agency is a digital agency based in Amsterdam that helps brands grow with strategy, content, technology and advertising working together as one digital ecosystem. Our development team builds and maintains websites and platforms (Laravel, Statamic, October CMS and WordPress) and uses these recipes to deploy them.

Contact

Questions, remarks or suggestions? Reach us at development@keyagency.nl.