Ansistrano

ansistrano.deploy and ansistrano.rollback are Ansible roles that simplify the deployment process for applications written in languages like PHP, Python, and Ruby. It is the Ansible version of Capistrano.

Table of Contents

• History
• Project name
• Usage statistics
• Who is using Ansistrano?
• Requirements
• Installation
• Updating
• Features
• Main workflow
• Role Variables
• Deploying
• Rolling back
• Custom tasks
• Variable use in custom tasks
• Cleaning up old releases
• Example Playbook
• Sample projects
• References
• License
• Additional resources

History

Capistrano is an automation tool for remote servers, currently at version 3. Version 2.0 was first designed to deploy Ruby on Rails applications but could also handle PHP and Python applications with plugins. However, Capistrano 2 is no longer maintained, and the newer version lacks some features making it less flexible. Therefore, Ansistrano was created as an alternative using Ansible for deployment tasks.

Project name

The name Ansistrano combines "Ansible" and "Capistrano."

Usage statistics

To gather anonymous usage data, Ansistrano sends a request to our servers. This data helps us understand how many users are active. If you prefer not to share data, set ansistrano_allow_anonymous_stats to false in your playbooks.

Who is using Ansistrano?

Ansistrano is in use by various companies including ABA English, Aptvision, and UNICEF Comité Español among others. If you're using Ansistrano, feel free to inform us.

Requirements

To deploy applications with Ansistrano, you need:

• Ansible installed on your deployment machine
• rsync on the target machine if using specific deployment strategies

Installation

Ansistrano is available through Ansible Galaxy. Install it using the following command:

$ ansible-galaxy install ansistrano.deploy ansistrano.rollback

Updating

To update the role, use the --force option:

$ ansible-galaxy install --force ansistrano.deploy ansistrano.rollback

Features

• Quick rollbacks with ansistrano.rollback
• Customize deployments with hooks before and after key actions
• Save disk space by limiting the number of releases stored
• Choose various deployment strategies like SCP, RSYNC, and GIT

Main workflow

Ansistrano follows a flow similar to Capistrano:

1. Setup phase: Create the folder structure.
2. Code update phase: Upload the new release.
3. Symlink phase: Update the current link to point to the new release.
4. Cleanup phase: Remove old releases based on the specified limit.

Role Variables

You can configure deployment with variables such as:

• ansistrano_deploy_from: Local project path
• ansistrano_deploy_to: Target deployment path
• ansistrano_current_dir: Name of the soft link for the current release
• ansistrano_keep_releases: Number of releases to retain after deployment

Deploying

To deploy with Ansistrano:

1. Create a hosts file specifying your target servers.
2. Create a playbook for deploying your application, like deploy.yml.
3. Set role variables.
4. Include ansistrano.deploy in your playbook.
5. Run the deployment using:

ansible-playbook -i hosts deploy.yml

Rolling back

To roll back:

1. Set up the rollback playbook.
2. Run:

ansible-playbook -i hosts rollback.yml

Custom tasks

You can perform additional tasks at different stages using hooks. For instance, restart a service after deployment, or clear cache.

Variable use in custom tasks

Some useful variables include:

• {{ ansistrano_release_path.stdout }}: Path to current release
• {{ ansistrano_shared_path }}: Path to shared assets

Cleaning up old releases

To manage the number of releases, set the ansistrano_keep_releases variable to your preferred number.

Example Playbook

For an example project, check the example folder to see how to deploy an application with Ansistrano.

Sample projects

We have added Ansistrano support for various projects, such as the LastWishes PHP Sample App.

References

• Deploying Symfony - Symfony Cat 2016

License

MIT

Additional resources

• Thoughts on deploying with Ansible
• Docker image