README

A configuration skeleton around the community ansistrano.deploy and ansistrano.rollback Ansible Galaxy roles. Those roles provide Capistrano style, zero-downtime, release-based deployment: each deploy lands in its own releases/<timestamp>/ directory, then a current symlink is atomically flipped to point at it. Rolling back is just moving that symlink to the previous release.

This wrapper adds no deployment engine of its own. Its job is to inject PHP and Laravel specific steps (cache warming, opcache reset, php-fpm reload, queue, Horizon, Reverb, Supervisor, cron, Slack notifications, and more) into Ansistrano's lifecycle hooks, each one toggled per server group by a simple variable.

Requirements

• Ansible on the control machine (the machine that runs the deploy).
• The two Galaxy roles listed in requirements.yml (ansistrano.deploy 3.14.0, ansistrano.rollback 3.1.0).
• SSH access from the control machine to your target servers.

Installation

Install this package into your PHP project as a dev dependency, then install the Galaxy roles.

composer require --dev longman/ansistrano
ansible-galaxy install -r vendor/longman/ansistrano/requirements.yml

The package expects to live at vendor/longman/ansistrano/ inside your project. That placement matters: vars/defaults.yml sets ansistrano_deploy_from to {{ playbook_dir }}/../../.., which walks three levels up from the package to your project root. The project root is what gets rsynced to the servers.

What your project must provide

The playbooks reference files that live in the consuming project, not in this package. Create these before your first deploy.

See example/vars.yml and example/hosts.ini for starting points.

Configuration

Configuration flows through two variable namespaces.

• ansistrano_* variables are consumed by the upstream role. They control the release mechanics (ansistrano_deploy_to, ansistrano_keep_releases, ansistrano_shared_paths, ansistrano_deploy_via, and the hook file bindings). Sensible defaults live in vars/defaults.yml.
• app_* variables are this wrapper's own convention. They fall into two groups: core settings that every deploy needs, and boolean feature toggles that turn individual post-deploy steps on or off.

Core variables

Set these in your inventory (see example/hosts.ini) or in build/ansible/vars.yml.

Feature toggles

Each optional step is gated by a variable. Boolean toggles use app_foo|bool == true; a few are presence based, meaning the step runs when the variable is simply defined. Set toggles per server group in your inventory's [group:vars] sections so each role (web, backend, task) runs only what it needs.

Steps run before the current symlink is flipped (they operate on the new release being built):

Steps run after the symlink flip (they operate on the live current release):

Supervisor config filenames default to the RHEL layout (/etc/supervisord.d/<domain>.ini). For the Debian/Ubuntu layout, override both the directory and the extension, for example app_supervisor_config_dest: /etc/supervisor/conf.d and app_supervisor_config_ext: conf. The same two variables also drive the Horizon and Reverb config filenames and the dynamic cleanup that removes them.

The presence of a non-empty app_slack_token enables a success notification at the end of a deploy and a failure notification if any task fails.

Usage

Run the playbooks from your project root, pointing -i at your inventory and naming the playbook inside the package.

# Deploy
ansible-playbook -i build/ansible/hosts.ini vendor/longman/ansistrano/deploy.yml

# Roll back one release
ansible-playbook -i build/ansible/hosts.ini vendor/longman/ansistrano/rollback.yml

# Tear down a dynamic deployment
ansible-playbook -i build/ansible/hosts.ini vendor/longman/ansistrano/cleanup.yml

deploy.yml and cleanup.yml set any_errors_fatal: true, so a failure on any host aborts the whole run.

Useful selectors while iterating:

ansible-playbook ... deploy.yml --syntax-check                      # parse only
ansible-playbook ... deploy.yml --check                            # dry run
ansible-playbook ... deploy.yml --limit task                       # one inventory group
ansible-playbook ... deploy.yml --tags pre                         # one lifecycle phase
ansible-playbook ... deploy.yml --start-at-task "APP | Restart Horizon"

Tasks are tagged on two axes: lifecycle phase (pre, post) and concern (app, server, dynamic). Combine with --tags to run a subset.

Deployment lifecycle

Ansistrano exposes hook points around its run. This wrapper binds a dispatcher file to each one in vars/defaults.yml. Every dispatcher is a list of conditional includes, so a step only runs when its toggle is set.

Dynamic deployments

Setting app_dynamic_deploy to true enables an ephemeral, per-domain deployment mode. On deploy it provisions a Route53 DNS record, the folder structure, NFS storage mounts, and an nginx vhost for app_domain. Each provisioning step has a teardown counterpart, all wired through cleanup.yml, so running the cleanup playbook removes everything the deploy created. The nginx vhost is further gated by app_dynamic_create_vhost, and the storage mount by the presence of app_dynamic_mount_path. These tasks run with privilege escalation and require AWS credentials (app_aws_access_key_id, app_aws_secret_access_key) for the DNS step.

Notes

• Two task files ship but are not wired into any hook: composer_optimize.yml and symlink_uploads.yml. Include them yourself if you need them.
• create_supervisor_config.yml and restart_supervisor_instance.yml are deprecated. Prefer the Laravel specific Supervisor tasks under config/tasks/laravel/.
• restart_phpfpm.yml reloads a hardcoded php74-php-fpm unit. Adjust it for your PHP version.
• The automatic rollback on failure is present but commented out in on_failure.yml.

License

Released under the MIT License. See LICENSE. Maintained by Avtandil Kikabidze (akalongman@gmail.com).