2019-02-07 23:59:02 +03:00
|
|
|
[![Build Status](https://travis-ci.org/stackbuilders/hapistrano.svg?branch=master)](https://travis-ci.org/stackbuilders/hapistrano)
|
|
|
|
[![Hackage version](https://img.shields.io/hackage/v/hapistrano.svg)](http://hackage.haskell.org/package/hapistrano)
|
|
|
|
[![Docker Hub](https://img.shields.io/docker/build/stackbuilders/hapistrano.svg?style=flat)](https://hub.docker.com/r/stackbuilders/hapistrano)
|
2014-06-04 20:59:35 +04:00
|
|
|
|
2020-10-15 18:34:25 +03:00
|
|
|
# Table of Contents
|
|
|
|
|
|
|
|
* [Hapistrano](#hapistrano)
|
|
|
|
* [Purpose](#purpose)
|
|
|
|
* [How it Works](#how-it-works)
|
|
|
|
* [Usage](#usage)
|
|
|
|
* [Environment Variables](#environment-variables)
|
|
|
|
* [What to do when compiling on server is not viable](#what-to-do-when-compiling-on-server-is-not-viable)
|
|
|
|
* [Deploying to multiple machines concurrently](#deploying-to-multiple-machines-concurrently)
|
|
|
|
* [Docker](#docker)
|
|
|
|
* [Nix](#nix)
|
|
|
|
* [License](#license)
|
|
|
|
* [Contributing](#contributing)
|
|
|
|
|
|
|
|
|
2014-06-04 04:17:20 +04:00
|
|
|
# Hapistrano
|
|
|
|
|
|
|
|
Hapistrano is a deployment library for Haskell applications similar to
|
|
|
|
Ruby's [Capistrano](http://capistranorb.com/).
|
|
|
|
|
|
|
|
## Purpose
|
|
|
|
|
|
|
|
We created Hapistrano because:
|
|
|
|
|
|
|
|
* Deploys should be simple, but as close to atomic as possible (eg,
|
|
|
|
they shouldn't require much application downtime).
|
|
|
|
* Rollback should be trivial to achieve to bring the application back
|
|
|
|
to the last-deployed state.
|
|
|
|
* Deploys shouldn't fail because of dependency problems.
|
|
|
|
|
|
|
|
## How it Works
|
|
|
|
|
|
|
|
Hapistrano (like Capistrano for Ruby) deploys applications to a new
|
|
|
|
directory marked with a timestamp on the remote host. It creates this
|
|
|
|
new directory quickly by placing a git repository for caching purposes
|
|
|
|
on the remote server.
|
|
|
|
|
2017-02-20 17:33:12 +03:00
|
|
|
When the build process completes, it switches a symlink to the `current`
|
|
|
|
release directory, and optionally restarts the web server.
|
2014-06-04 04:17:20 +04:00
|
|
|
|
|
|
|
By default, Hapistrano keeps the last five releases on the target host
|
|
|
|
filesystem and deletes previous releases to avoid filling up the disk.
|
|
|
|
|
|
|
|
## Usage
|
|
|
|
|
2020-03-30 03:54:39 +03:00
|
|
|
Hapistrano 0.4.0.0 looks for a configuration file called `hap.yaml` that
|
2017-02-20 17:33:12 +03:00
|
|
|
typically looks like this:
|
|
|
|
|
|
|
|
```yaml
|
|
|
|
deploy_path: '/var/projects/my-project'
|
|
|
|
host: myserver.com
|
|
|
|
port: 2222
|
2020-03-30 03:54:39 +03:00
|
|
|
# To perform version control operations
|
2017-02-20 17:33:12 +03:00
|
|
|
repo: 'https://github.com/stackbuilders/hapistrano.git'
|
|
|
|
revision: origin/master
|
2020-03-30 03:54:39 +03:00
|
|
|
# To copy the contents of the directory
|
|
|
|
local_directory: '/tmp/my-project'
|
2017-02-20 17:33:12 +03:00
|
|
|
build_script:
|
|
|
|
- stack setup
|
|
|
|
- stack build
|
|
|
|
restart_command: systemd restart my-app-service
|
|
|
|
```
|
|
|
|
|
|
|
|
The following parameters are required:
|
|
|
|
|
|
|
|
* `deploy_path` — the root of the deploy target on the remote host.
|
2020-03-30 03:54:39 +03:00
|
|
|
* Related to the `source` of the repository, you have the following options:
|
|
|
|
- _Git repository_ **default** — consists of two parameters. When these are set,
|
|
|
|
hapistrano will perform version control related operations.
|
|
|
|
**Note:** Only GitHub is supported.
|
|
|
|
* `repo` — the origin repository.
|
|
|
|
* `revision` — the SHA1 or branch to deploy. If a branch, you will need to
|
|
|
|
specify it as `origin/branch_name` due to the way that the cache repo is
|
|
|
|
configured.
|
|
|
|
* `local_directory` — when this parameter is set, hapistrano will copy the
|
|
|
|
contents of the directory.
|
2017-02-20 17:33:12 +03:00
|
|
|
|
|
|
|
The following parameters are *optional*:
|
|
|
|
|
|
|
|
* `host` — the target host, if missing, `localhost` will be assumed (which
|
|
|
|
is useful for testing and playing with `hap` locally).
|
|
|
|
* `port` — SSH port number to use. If missing, 22 will be used.
|
2019-01-09 21:49:43 +03:00
|
|
|
* `shell` — Shell to use. Currently supported: `zsh` ans `bash`. If missing, `Bash` will be used.
|
2019-10-29 00:23:01 +03:00
|
|
|
* `ssh_args` — Optional ssh arguments. Only `-p` is passed via the `port` variable.
|
2017-02-20 17:33:12 +03:00
|
|
|
* `build_script` — instructions how to build the application in the form of
|
|
|
|
shell commands.
|
|
|
|
* `restart_command` — if you need to restart a remote web server after a
|
|
|
|
successful rollback, specify the command that you use in this variable. It
|
|
|
|
will be run after both deploy and rollback.
|
2017-04-05 20:57:50 +03:00
|
|
|
* `vc_action` - Controls if version control related activity should
|
|
|
|
take place. It defaults to true. When you don't want activity like
|
|
|
|
cloning, fetching etc. to take place, set this to `false`.
|
2017-11-27 22:36:33 +03:00
|
|
|
* `linux` - Specify, whether or not, the target system where Hapistrano will
|
|
|
|
deploy to is a GNU/Linux or other UNIX (g.e. BSD, Mac). This is set to `true`
|
|
|
|
by default so unless the target system is not GNU/Linux, this should not be
|
|
|
|
necessary. The platform where Hapistrano is running won't affect the
|
|
|
|
available options for commands (g.e. A Mac deploying to a Ubuntu machine,
|
|
|
|
doesn't need this flag)
|
2018-10-22 18:18:53 +03:00
|
|
|
* `release_format` - The release timestamp format, the
|
2018-10-19 22:01:28 +03:00
|
|
|
'--release-format' argument passed via the CLI takes precedence over this
|
|
|
|
value. If neither CLI or configuration file value is specified, it defaults
|
|
|
|
to 'short'
|
2018-10-22 18:18:53 +03:00
|
|
|
* `keep_releases` - The number of releases to keep, the
|
2018-10-19 22:01:28 +03:00
|
|
|
'--keep-releases' argument passed via the CLI takes precedence over this
|
|
|
|
value. If neither CLI or configuration file value is specified, it defaults
|
|
|
|
to '5'
|
2019-01-09 20:05:37 +03:00
|
|
|
* `linked_files:`- Listed files that will be symlinked from the `{deploy_path}/shared` folder
|
|
|
|
into each release directory during deployment. Can be used for configuration files
|
|
|
|
that need to be persisted (e.g. dotenv files). **NOTE:** The directory structure _must_
|
|
|
|
be similar in your release directories in case you need to link a file inside a
|
|
|
|
nested directory (e.g. `shared/foo/file.txt`).
|
|
|
|
* `linked_dirs:`- Listed directories that will be symlinked from the `{deploy_path}/shared` folder
|
|
|
|
into each release directory during deployment. Can be used for data directories
|
|
|
|
that need to be persisted (e.g. upload directories). **NOTE:** Do not add a slash `/`
|
|
|
|
at the end of the directory (e.g. `foo/`) because we use `parseRelFile` to create
|
|
|
|
the symlink.
|
2017-08-30 00:59:13 +03:00
|
|
|
* `run_locally:`- Instructions to run locally on your machine in the
|
|
|
|
form of shell commands. Example:
|
|
|
|
|
|
|
|
```
|
|
|
|
run_locally:
|
|
|
|
- pwd
|
|
|
|
- bash deploy.sh
|
|
|
|
```
|
2017-02-20 17:33:12 +03:00
|
|
|
|
2017-08-30 01:13:49 +03:00
|
|
|
Note how we are even able to execute a bash script named `deploy.sh`
|
|
|
|
above. Be sure to use `set -e` in your bash script to avoid
|
|
|
|
headaches. Hapistrano will stop the execution on non zero exit
|
|
|
|
codes. Without the usage of `set -e`, there is a possiblity that your
|
|
|
|
bash script may return a zero exit code even if your intermediate
|
|
|
|
command resulted in an error.
|
|
|
|
|
2017-02-20 17:33:12 +03:00
|
|
|
After creating a configuration file as above, deploying is as simple as:
|
|
|
|
|
|
|
|
```bash
|
|
|
|
$ hap deploy
|
|
|
|
```
|
|
|
|
|
|
|
|
Rollback is also trivial:
|
|
|
|
|
|
|
|
```bash
|
|
|
|
$ hap rollback # to rollback to previous successful deploy
|
|
|
|
$ hap rollback -n 2 # go two deploys back in time, etc.
|
|
|
|
```
|
2015-03-13 05:12:35 +03:00
|
|
|
|
2018-09-21 16:32:23 +03:00
|
|
|
### Environment Variables
|
|
|
|
|
|
|
|
Configuration files are parsed using
|
|
|
|
[loadYamlSettings](http://hackage.haskell.org/package/yaml-0.10.2.0/docs/Data-Yaml-Config.html#v:loadYamlSettings),
|
|
|
|
therefore, variable substitution is supported. Considering the following configuration file:
|
|
|
|
|
|
|
|
```yaml
|
|
|
|
revision: "_env:HAPISTRANO_REVISION:origin/master
|
|
|
|
...
|
|
|
|
```
|
|
|
|
|
|
|
|
The `revision` value could be overwritten as follows:
|
|
|
|
|
|
|
|
```sh
|
|
|
|
HAPISTRANO_REVISION=origin/feature_branch hap deploy
|
|
|
|
```
|
|
|
|
|
2017-02-20 18:09:21 +03:00
|
|
|
## What to do when compiling on server is not viable
|
|
|
|
|
|
|
|
Sometimes the target machine (server) is not capable of compiling your
|
|
|
|
application because e.g. it has not enough memory and GHC exhausts it all.
|
|
|
|
You can copy pre-compiled files from local machine or CI server using
|
|
|
|
`copy_files` and `copy_dirs` parameters:
|
|
|
|
|
|
|
|
```haskell
|
|
|
|
copy_files:
|
|
|
|
- src: '/home/stackbuilders/my-file.txt'
|
|
|
|
dest: 'my-file.txt'
|
|
|
|
copy_dirs:
|
|
|
|
- src: .stack-work
|
|
|
|
dest: .stack-work
|
|
|
|
```
|
|
|
|
|
|
|
|
`src` maybe absolute or relative, it's path to file or directory on local
|
|
|
|
machine, `dest` may only be relative (it's expanded relatively to cloned
|
|
|
|
repo) and specifies where to put the files/directories on target machine.
|
|
|
|
Directories and files with clashing names will be overwritten. Directories
|
|
|
|
are copied recursively.
|
|
|
|
|
2017-03-01 23:40:08 +03:00
|
|
|
## Deploying to multiple machines concurrently
|
|
|
|
|
|
|
|
Beginning with Hapistrano 0.3.1.0 it's possible to deploy to several
|
|
|
|
machines concurrently. The only things you need to do is to adjust your
|
|
|
|
configuration file and use `targets` parameter instead of `host` and `port`,
|
|
|
|
like this:
|
|
|
|
|
|
|
|
```haskell
|
|
|
|
targets:
|
|
|
|
- host: myserver-a.com
|
|
|
|
port: 2222
|
2017-03-12 00:58:16 +03:00
|
|
|
- host: myserver-b.com
|
2017-03-01 23:40:08 +03:00
|
|
|
# the rest is the same…
|
|
|
|
```
|
|
|
|
|
|
|
|
A few things to note here:
|
|
|
|
|
|
|
|
* `host` item is required for every target, but `port` may be omitted and
|
|
|
|
then it defaults to `22`.
|
|
|
|
|
|
|
|
* The deployment will run concurrently and finish when interactions with all
|
|
|
|
targets have finished either successfully or not. If at least one
|
|
|
|
interaction was unsuccessful, the `hap` tool will exit with non-zero exit
|
|
|
|
code.
|
|
|
|
|
2017-04-05 20:57:50 +03:00
|
|
|
* The log is printed in such a way that messages from several machines get
|
2017-03-01 23:40:08 +03:00
|
|
|
intermixed, but it's guaranteed that they won't overlap (printing itself
|
|
|
|
is sequential) and the headers will tell you exactly which machine was
|
|
|
|
executing which command.
|
|
|
|
|
|
|
|
If you don't specify `host` and `targets`, `hap` will assume `localhost` as
|
|
|
|
usually, which is mainly useful for testing.
|
|
|
|
|
2018-05-22 17:03:00 +03:00
|
|
|
## Docker
|
|
|
|
|
2018-10-22 18:18:53 +03:00
|
|
|
If you would like to use Docker, there is a lightweight image
|
2018-05-22 17:03:00 +03:00
|
|
|
available on [Docker Hub](https://hub.docker.com/r/stackbuilders/hapistrano/).
|
|
|
|
|
2019-11-07 00:25:05 +03:00
|
|
|
## Nix
|
|
|
|
|
|
|
|
If you want to use Nix for building Hapistrano, the required release.nix and default.nix are available.
|
2019-11-07 00:26:31 +03:00
|
|
|
|
2020-03-30 03:54:39 +03:00
|
|
|
For installing the hap binary in your local path:
|
|
|
|
```bash
|
2019-11-07 00:25:05 +03:00
|
|
|
nix-env -i hapistrano -f release.nix
|
|
|
|
```
|
|
|
|
For developing Hapistrano with Nix, you can create a development environment using:
|
|
|
|
```bash
|
|
|
|
nix-shell --attr env release.nix
|
|
|
|
```
|
|
|
|
|
|
|
|
For just building Hapistrano, you just:
|
|
|
|
```bash
|
|
|
|
nix-build release.nix
|
|
|
|
```
|
|
|
|
|
|
|
|
|
2017-02-20 18:09:21 +03:00
|
|
|
## License
|
2014-06-04 15:25:29 +04:00
|
|
|
|
|
|
|
MIT, see [the LICENSE file](LICENSE).
|
2014-06-04 04:17:20 +04:00
|
|
|
|
2017-02-20 18:09:21 +03:00
|
|
|
## Contributing
|
2014-06-04 04:17:20 +04:00
|
|
|
|
|
|
|
Pull requests for modifications to this program are welcome. Fork and
|
|
|
|
open a PR. Feel free to [email me](mailto:justin@stackbuilders.com) if
|
|
|
|
you have questions about what may be accepted before working on a PR.
|
2014-06-04 18:04:41 +04:00
|
|
|
|
|
|
|
If you're looking for a place to start, you may want to check the
|
|
|
|
[open issue](https://github.com/stackbuilders/hapistrano/issues).
|