The hapistrano package

[Tags:library, mit, program, test]

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]

Properties

Versions 0.1.0.0, 0.1.0.1, 0.1.0.2, 0.2.0.1, 0.2.0.2, 0.2.1, 0.2.1.1, 0.2.1.2, 0.3.0.0, 0.3.0.1
Change log CHANGELOG.md
Dependencies aeson (>=0.11 && <1.2), base (>=4.6 && <5.0), filepath (>=1.2 && <1.5), hapistrano, mtl (>=2.0 && <3.0), optparse-applicative (>=0.11 && <0.14), path (>=0.5.8 && <6.0), path-io (==1.2.*), process (==1.4.*), time (>=1.5 && <1.8), transformers (>=0.4 && <0.6), yaml (==0.8.*) [details]
License MIT
Copyright 2015-2017 Stack Builders Inc.
Author Justin Leitgeb
Maintainer justin@stackbuilders.com
Stability Unknown
Category System
Home page https://github.com/stackbuilders/hapistrano
Bug tracker https://github.com/stackbuilders/hapistrano/issues
Source repository head: git clone https://github.com/stackbuilders/hapistrano.git
Uploaded Tue Feb 21 18:49:06 UTC 2017 by mrkkrp
Distributions LTSHaskell:0.2.1.2, NixOS:0.2.1.2, Stackage:0.3.0.1, Tumbleweed:0.2.1.2
Downloads 1167 total (36 in the last 30 days)
Votes
0 []
Status Docs available [build log]
Last success reported on 2017-02-21 [all 1 reports]

Modules

[Index]

Flags

NameDescriptionDefaultType
devTurn on development settings.DisabledManual

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

Downloads

Maintainer's Corner

For package maintainers and hackage trustees

Readme for hapistrano

Readme for hapistrano-0.3.0.1

Build Status Hackage version

Hapistrano

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

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.

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.

Usage

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

deploy_path: '/var/projects/my-project'
host: myserver.com
port: 2222
repo: 'https://github.com/stackbuilders/hapistrano.git'
revision: origin/master
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.
  • 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.

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.
  • 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.

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.

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:

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.

License

MIT, see the LICENSE file.

Contributing

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.