Project Deployment Module (deploy_helper)

=========

The deploy_helper module is designed for use with ansible-modules-extra.

Overview with Example Folder Structure

Here's how you might organize your project folder:

root:
    releases:
        - 20140415234508
        - 20140415235146
        - 20140416082818

    shared:
        - sessions
        - uploads

    current: -> releases/20140416082818

• The releases folder contains all releases of your application. Each release is a full version of your app, which could be a clone of a repository or synced from a local folder. Using timestamps for folders is one way to differentiate between releases, but you can also use methods like git tags or commit hashes.

• When you deploy, you create a new folder in the releases folder and run any necessary build steps. After the build is ready, you update the current symlink to point to the new release.

• The shared folder contains resources used by all releases, like session files or user-uploaded files. Typically, you'll create symlinks from the release folder to the shared folder during the build steps.

• The current symlink points to the latest release. This minimizes downtime when switching to a new version, as the web server accesses the project root via this symlink.

• To identify ongoing builds, you can place a specific file in the release folder. If this file exists, it marks the build as unfinished, allowing automatic cleanup later.

Typical Usage

Here’s how you can use the deploy_helper:

- name: Set up the deployment root and gather information
  deploy_helper: path=/path/to/root

- name: Clone the project into a new release folder
  git: repo=git://foosball.example.org/path/to/repo.git dest={{ deploy_helper.new_release_path }} version=v1.1.1

- name: Create an unfinished marker file for cleanup upon success
  file: path={{ deploy_helper.new_release_path }}/{{ deploy_helper.unfinished_filename }} state=touch

- name: Execute build steps such as dependency installation
  composer: command=install working_dir={{ deploy_helper.new_release_path }}

- name: Create directories in the shared folder
  file: path='{{ deploy_helper.shared_path }}/{{ item }}' state=directory
  with_items: ['sessions', 'uploads']

- name: Link new release folders to the shared folder
  file: path='{{ deploy_helper.new_release_path }}/{{ item.path }}'
        src='{{ deploy_helper.shared_path }}/{{ item.src }}'
        state=link
  with_items:
      - { path: "app/sessions", src: "sessions" }
      - { path: "web/uploads", src: "uploads" }

- name: Finalize the deployment, remove unfinished marker and update the symlink
  deploy_helper: path=/path/to/root release={{ deploy_helper.new_release }} state=finalize

Gathering Facts Before Deployment

To check the current state without changing anything:

- name: Run 'state=query' for information
  deploy_helper: path=/path/to/root state=query

Set the Release Parameter When Deploying

When you want to initialize the deployment with a release:

- name: Initialize the deploy root
  deploy_helper: path=/path/to/root release={{ deploy_helper.new_release }} state=present

Working with Paths

• You can define absolute or relative paths:

- deploy_helper: path=/path/to/root
                 releases_path=/var/www/project/releases
                 shared_path=/var/www/shared
                 current_path=/var/www/active

Using Your Own Release Naming Strategy (e.g., Version Tag)

- deploy_helper: path=/path/to/root release=v1.1.1 state=present
- deploy_helper: path=/path/to/root release={{ deploy_helper.new_release }} state=finalize

Customizing the Unfinished Filename

- deploy_helper: path=/path/to/root
                 unfinished_filename=README.md
                 release={{ deploy_helper.new_release }}
                 state=finalize

Delaying Cleanup of Older Builds

- deploy_helper: path=/path/to/root release={{ deploy_helper.new_release }} state=finalize clean=False
- deploy_helper: path=/path/to/root state=clean

Performing Cleanup Before New Deployment

- deploy_helper: path=/path/to/root state=clean
- deploy_helper: path=/path/to/root state=present

Keeping More Old Releases

- deploy_helper: path=/path/to/root release={{ deploy_helper.new_release }} state=finalize keep_releases=10

Removing Project Root Folder

- deploy_helper: path=/path/to/root state=absent

Debugging Returned Facts

You can print out the returned facts for debugging:

- deploy_helper: path=/path/to/root
- debug: var=deploy_helper

License

The module is licensed under LGPL.

Author Information

Created by Ramon de la Fuente, ramon@delafuente.nl.