deployer: the PHP deployment tool whose README is a business card

Three bullets, a logo and a link to the documentation

The README for this project is unusually short. After the logo and a one-line description, it lists three features: automatic server provisioning, zero downtime deployments, and ready to use recipes for most frameworks. Then it adds two related links, a GitHub Action for Deployer and a Docker image on Docker Hub, and stops.

The features are stated without elaboration, which means the interesting questions are all deferred to deployer.org. What zero downtime means in Deployer, which frameworks have recipes, how provisioning works, none of it is in the repository. That is a deliberate choice rather than an oversight, and it tells you something about where the documentation burden sits: the site is the manual, the repository is the source.

The remaining README content is metadata. Build status and latest stable version badges come from GitHub Actions and Packagist, the license badge says MIT, and the license itself links to the LICENSE file in the repository. The repository topics are deploy, deployment, php, provision and tool, which is an accurate five-word summary of the project.

The recipe directory is the actual product

The tree explains what Deployer is for. `recipe/` holds one directory per framework, and that is where the framework support in the feature list lives. `src/` is the tool itself, `bin/` the entry point, and `tests/` and `phpunit.xml` the test suite. `docs/` exists in the tree as well, and `.github/` holds the workflows behind the build badge.

bin/
contrib/
docs/
recipe/
src/
tests/
composer.json
Dockerfile
SECURITY.md

`contrib/` is worth a mention because it is the extension point for anything not shipped in the core. A framework with no maintained recipe, or a hosting target Deployer does not know about, is the case that directory exists for.

The two static analysis and style files at the tree root say something about how the project is policed. `phpstan.neon` means types are checked with PHPStan, and `.php-cs-fixer.dist.php` means formatting is enforced by php-cs-fixer rather than left to reviewers. For a tool that ends up running with production credentials on a server, that is the sort of housekeeping worth noticing.

The Docker image is a phar and a set of system tools

The `Dockerfile` at the tree root is short enough to read in full, and it explains how Deployer is meant to run in a container. It starts from the PHP 8.5 CLI image on Alpine and installs the command line tools a deploy needs: git, rsync, openssh-client, zip and unzip, plus libzip.

FROM php:8.5-cli-alpine

RUN set -eux; \
    apk add --no-cache \
        bash \
        git \
        libzip \
        openssh-client \
        rsync \
        unzip \
        zip; \
    docker-php-ext-install -j"$(nproc)" pcntl sockets zip; \
    apk del .build-deps

The PHP extensions installed are `pcntl`, `sockets` and `zip`, and the build dependencies are removed in the same layer that used them, which keeps the final image small. The image then expects a `deployer.phar` to be copied in, renamed to `/bin/dep` with execute permission, and run as the entrypoint from a `/app` working directory.

Two things follow. First, Deployer distributes as a phar, which is why the phar has to be staged separately before the image builds. Second, the tool list tells you what a deployment actually needs at the system level: rsync for file transfer, ssh for the remote side, and git because a deploy almost always starts from a commit.

Recent releases are SSH and recipe bug fixes

The three most recent releases are all patches, and two of them are about SSH, which is the component Deployer leans on hardest. Version 8.0.5, published 2026-05-18, fixed SSH timeout errors being masked by a failed kill cleanup, and fixed possible infinite recursion when the cleanup command itself timed out. Version 8.0.3 on 2026-05-05 fixed SSH connection options for the ssh command.

Those two issues are the kind that are miserable in production. A timeout that gets swallowed by a cleanup failure turns a clear error into a hang, and an infinite recursion in cleanup is worse. The fact that both were addressed inside a week of each other suggests the SSH layer was getting real attention rather than routine bumps.

Version 8.0.4, published between them on 2026-05-16, went the other way and fixed a recipe: the Magento recipe needed an extra import step after a deployment failed mid-upgrade. That is the clearest example of the project's structure showing through its changelog. Recipes live in the same release train as the tool, and a framework's deploy sequence can change because of a version bump in that framework rather than in Deployer.

The default branch is `master`, the source language is PHP, and the licence is MIT.

What the documentation site has to carry

Everything a user actually needs is on deployer.org, and the list of what has to be there is long. How to write a `deploy.php` recipe, how repository and host configuration are shared between local and remote runs, what the built-in tasks do, how to write a custom task, how parallel execution across hosts is configured, and how the rollback story works.

That last group is where a deployment tool earns or loses trust, and none of it is in the repository. Zero downtime in particular is a claim that needs a mechanism behind it, and the README does not say whether that is a symlink swap, a directory rename, or something else. Provisioning is similarly a bare word in the feature list.

The repository does contain a `SECURITY.md`, which is the right signal for a tool that handles SSH keys and production credentials. There is also a GitHub Action maintained separately at `deployphp/action` for running Deployer inside a pipeline, and the Docker Hub image linked from the README for running it as a container.

So the honest summary of where this project lives is: the repository is where you read the source and file issues, and the website is where you read the documentation. That split is common in older PHP projects and it is the main friction for anyone arriving from a tool like Envoy where everything used to live in one place.

How Deployer compares to the alternatives

Against a hand-rolled bash script, the argument is reviewability. A recipe is a PHP file in your project repository, so a deploy change shows up in a pull request and the person approving it can read what will happen to production. Scripts written by one person and run by another are the usual failure mode here.

Against a platform like Deployer-free continuous delivery services, the argument is that nothing leaves your own infrastructure. Deployer runs over SSH on servers you control, using keys you hold. The cost is that you own the rollback, the monitoring and the upgrade path for the tool itself.

Against Capistrano, which occupies the same niche for Ruby, Deployer is a PHP-native answer with framework recipes for the PHP ecosystem rather than a Ruby tool people bent toward PHP projects.

The practical decision comes down to whether your framework already has a maintained recipe and whether your hosting gives you SSH access. Both are usually true. Where it is not, `contrib/` is where you would look for a community recipe, and a custom task is the documented fallback.

Editorial conclusion

Deployer is one of those tools whose usefulness is invisible in its README. Three feature bullets, a screenshot, and a pointer to deployer.org is the entire pitch, and the actual product is `recipe/`, a directory of framework recipes that turns a deploy from a bespoke shell script into a reviewed config file. The trade is that you will not learn the tool from the repository: recipes are read from the docs site, and the source in `src/` is where you look when a recipe does not match your setup. Version 8.0.5 shipped on 2026-05-18 with SSH cleanup fixes and the last push was on 2026-08-26, so the maintenance signal is steady rather than dramatic.

Frequently asked questions

Official sources

1. deployphp/deployer on GitHub
2. License: MIT
3. Project website
4. README
5. Releases