zicht / z-plugin-deploy
Deploy plugin for Z
Requires
This package is auto-updated.
Last update: 2024-10-16 01:07:13 UTC
README
This plugin provides tasks to build and deploy the current project:
deploy
task to build and deploy the project to a specific environmentsimulate
task to build and simulate a deploy of the project against a specific environmentredeploy
task to rebuild and redeploy the version of the project currently on a specific environmentpatch
task to patch a specific environmentunpatch
task to revert a patch on a specific environmentqdeploy
task to build the project and patch a specific environmentqsimulate
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.
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).
The general approach for this implementation is:
- 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
'spost
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
'spost
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.
Add exclude file to your project
By default, the rsync
plugin expects you to add an rsync file to your project:
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:
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.
$ 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.
Now, you can also simulate the deploy, which would execute everything except
for the deploy post
triggers:
z simulate prod
And if that succeeds:
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 usingz 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 outpwd
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.
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