hapistrano: A deployment library for Haskell applications

This is a package candidate release! Here you can preview how this package release will appear once published to the main package index (which can be accomplished via the 'maintain' link below). Please note that once a package has been published to the main package index it cannot be undone! Please consult the package uploading documentation for more information.

[maintain] [Publish]


Hapistrano makes it easy to reliably deploy Haskell applications to a server.

Following popular libraries like Ruby's <http://capistranorb.com/ Capistrano>, Hapistrano does the work of building the application with dependencies into a distinct folder, and then atomically moves a symlink to the latest complete build.

This allows for atomic switchovers to new application code after the build is complete. Rollback is even simpler, since Hapistrano can just point the current symlink to the previous release.

See the project readme on GitHub for more information.

[Skip to Readme]


Versions,,,,, 0.2.1,,,,,,,,,,,,,,,,,,,,,,,,,,,,,,,,,,,,,,,,,,,,,,,,
Change log CHANGELOG.md
Dependencies aeson (>=0.11 && <1.6), ansi-terminal (>=0.9 && <0.12), async (>= && <2.4), base (>=4.8 && <5.0), filepath (>=1.2 && <1.5), formatting (>=6.2 && <7.0), gitrev (>=1.2 && <1.4), hapistrano, mtl (>=2.0 && <3.0), optparse-applicative (>=0.11 && <0.16), path (>=0.5 && <0.8), path-io (>=1.2 && <1.7), process (>=1.4 && <1.7), stm (>=2.4 && <2.6), time (>=1.5 && <1.11), transformers (>=0.4 && <0.6), typed-process (>=0.2 && <0.3), yaml (>=0.8.16 && <0.12) [details]
License MIT
Copyright 2015-Present Stack Builders Inc.
Author Justin Leitgeb
Maintainer jpaucar@stackbuilders.com
Category System
Home page https://github.com/stackbuilders/hapistrano
Bug tracker https://github.com/stackbuilders/hapistrano/issues
Source repo head: git clone https://github.com/stackbuilders/hapistrano.git
Uploaded by juanpaucar at 2020-08-13T22:05:46Z


[Index] [Quick Jump]


Manual Flags


Turn on development settings.


Build a static binary.


Use -f <flag> to enable a flag, or -f -<flag> to disable that flag. More info


Maintainer's Corner

Package maintainers

For package maintainers and hackage trustees

Readme for hapistrano-

[back to package description]

Build Status Hackage version Docker Hub


Hapistrano is a deployment library for Haskell applications similar to Ruby's Capistrano.


We created Hapistrano because:

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.

When the build process completes, it switches a symlink to the current release directory, and optionally restarts the web server.

By default, Hapistrano keeps the last five releases on the target host filesystem and deletes previous releases to avoid filling up the disk.


Hapistrano looks for a configuration file called hap.yaml that typically looks like this:

deploy_path: '/var/projects/my-project'
host: myserver.com
port: 2222
# To perform version control operations
repo: 'https://github.com/stackbuilders/hapistrano.git'
revision: origin/master
# To copy the contents of the directory
local_directory: '/tmp/my-project'
  - stack setup
  - stack build
restart_command: systemd restart my-app-service

The following parameters are required:

The following parameters are optional:

  - pwd
  - bash deploy.sh

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.

After creating a configuration file as above, deploying is as simple as:

$ hap deploy

Rollback is also trivial:

$ hap rollback # to rollback to previous successful deploy
$ hap rollback -n 2 # go two deploys back in time, etc.

Environment Variables

Configuration files are parsed using loadYamlSettings, therefore, variable substitution is supported. Considering the following configuration file:

revision: "_env:HAPISTRANO_REVISION:origin/master

The revision value could be overwritten as follows:

HAPISTRANO_REVISION=origin/feature_branch hap deploy

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:

  - src: '/home/stackbuilders/my-file.txt'
    dest: 'my-file.txt'
  - 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.

Deploying to multiple machines concurrently

Beginning with Hapistrano 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:

  - host: myserver-a.com
    port: 2222
  - host: myserver-b.com
# the rest is the same…

A few things to note here:

If you don't specify host and targets, hap will assume localhost as usually, which is mainly useful for testing.


If you would like to use Docker, there is a lightweight image available on Docker Hub.


If you want to use Nix for building Hapistrano, the required release.nix and default.nix are available.

For installing the hap binary in your local path:

nix-env -i hapistrano -f release.nix

For developing Hapistrano with Nix, you can create a development environment using:

nix-shell --attr env release.nix

For just building Hapistrano, you just:

nix-build release.nix


MIT, see the LICENSE file.


Pull requests for modifications to this program are welcome. Fork and open a PR. Feel free to email me if you have questions about what may be accepted before working on a PR.

If you're looking for a place to start, you may want to check the open issue.