zicht/z-plugin-deploy

Deploy plugin for Z

Z-plugin to provide deploy tasks

This plugin provides tasks to build and deploy the current project:, _(*1)

• deploy task to build and deploy the project to a specific environment
• simulate task to build and simulate a deploy of the project against a specific environment
• redeploy task to rebuild and redeploy the version of the project currently on a specific environment
• patch task to patch a specific environment
• unpatch task to revert a patch on a specific environment
• qdeploy task to build the project and patch a specific environment
• qsimulate task to build the project and simulate patching a specific environment

Usage

Setting up Z

See the documentation for zicht/z for more information on how to install Z with plugins., _(*2)

General approach

NOTE this setup requires a few other plugins. You are not required to use those, but this is what a typical setup would look like (following this deployment scheme)., _(*3)

The general approach for this implementation is:, _(*4)

• A build is created in a separate folder by cloning the current working directory into a separate build directory (git plugin handles this)
• All other plugins have the chance to hook into the build by attaching themselves to the build's post trigger (common Z functionality, you can hook into any task like this)
• An rsync is executed to a remote SSH environment (rsync plugin handles this)
• Do more housekeeping in the deploy's post trigger.

The deploy plugin also provides a simulate task, which creates a build and runs the rsync with a --dry-run flag, so you can see what would be synced., _(*5)

Add exclude file to your project

By default, the rsync plugin expects you to add an rsync file to your project:, _(*6)

echo ".git/" >> ./rsync.exclude
git add rsync.exclude
git commit -m"add rsync.exclude" ./rsync.exclude

Then, you will require a z file in your project:, _(*7)

plugins: ['env', 'build', 'deploy', 'git', 'rsync']


envs:
    prod:
        ssh: myuser@prod-machine
        root: ~/my-project-path
        web: public    # the relative path to the public web folder within the project path

tasks:
    build:
        post:
            - echo "I am just adding a random file here" >> $(path(build.dir, "foo.html"))

    deploy:
        post:
            - echo "Thank you, come again"

If you explain the deploy, you would see every step being explained in bash. Read more about what --explain does in the documentation for Z., _(*8)

$ z --explain deploy prod
echo 'echo "Checking out version foo to ./build";' | /bin/bash -e
echo 'git clone . ./build' | /bin/bash -e
echo 'cd ./build && git checkout foo' | /bin/bash -e
echo 'cd ./build && git log HEAD -1 > .z.rev' | /bin/bash -e
echo 'echo "I am just adding a random file here" >> ./build/foo.html' | /bin/bash -e
echo 'rsync \
     \
    -rpcl --delete  \
        --exclude-from=./build/rsync.exclude \
        -v \
    ./build/ myuser@production-machine:~/my-project-path/ \
;' | /bin/bash -e
echo 'echo "Thank you, come again"' | /bin/bash -e

As you can see, each line within this explanation reflects a step in the build process., _(*9)

Now, you can also simulate the deploy, which would execute everything except for the deploy post triggers:, _(*10)

z simulate prod

And if that succeeds:, _(*11)

z deploy prod

Common issues you should check:

• Can you login to the SSH remote? Check this with z env:ssh prod. It is advisable to publish your key to the remote using z env:ssh-copy-id prod you you can access the remote passwordless.
• Does the remote directory exist? env tries to open the ssh session within the remote directory. Use this to check your setup: z env:ssh prod pwd (or leave out pwd to run it interactively).
• Is the rsync file available in the build? You can create the build and inspect it yourself

Note that you can always use --explain to introspect what the plugins and/or Z try to do. To get even more information, you can combine --explain and --debug, you can see where certain task lines originate from., _(*12)

Considerations

• You can add your own mix of plugins to prepare javascript/css files, add credentials to your build, etc, etc. However, a lot of common usage plugins are already available. These include things like:
  • npm, bower, typescript, babel, etc
  • sass, post-css
  • chmod
• As soon as you find you are copying-and-pasting your z.yml files across projects, you should consider creating plugins.

Maintainer(s)

• Jochem Klaver jochem@zicht.nl