* Create maintenance command * Read filepath and filename zsh:1: command not found: q * Addd config and test * Addd config and test * Add tests and imports * Add test for writing maintenance file Co-authored-by: Cristhian Motoche <CristhianMotoche@users.noreply.github.com> * Expand writeMaintenancFile function Co-authored-by: Cristhian Motoche <CristhianMotoche@users.noreply.github.com> * Add functionality for command enable Co-authored-by: Cristhian Motoche <CristhianMotoche@users.noreply.github.com> * Add delete function * Add filename and directory from configPath zsh:1: command not found: wq * Remove unused file * Change variable name * Remove Utils from cabal file * Remove environment file * Change pattern * Add suggested formatting and comments * Add more suggestions and option to run stack * Update README with new variables * Update README with changes Co-authored-by: Cristhian Motoche <CristhianMotoche@users.noreply.github.com>
11 KiB
Hapistrano
- Description
- Purpose
- How it Works
- Usage
- What to do when compiling on server is not viable
- Deploying to multiple machines concurrently
- Docker
- Nix
- Notes
- License
- Contributing
Description
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.4.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
# 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'
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.- 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 asorigin/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.
- Git repository default — consists of two parameters. When these are set,
hapistrano will perform version control related operations.
Note: Only GitHub is supported.
The following parameters are optional:
host
— the target host, if missing,localhost
will be assumed (which is useful for testing and playing withhap
locally).port
— SSH port number to use. If missing, 22 will be used.shell
— Shell to use. Currently supported:zsh
ansbash
. If missing,Bash
will be used.ssh_args
— Optional ssh arguments. Only-p
is passed via theport
variable.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.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 tofalse
.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 totrue
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 an Ubuntu machine, doesn't need this flag)release_format
- The release timestamp format, the '--release-format' argument passed via the CLI takes precedence over this value. If neither CLI nor configuration file value is specified, it defaults to 'short'keep_releases
- The number of releases to keep, the '--keep-releases' argument passed via the CLI takes precedence over this value. If neither CLI nor configuration file value is specified, it defaults to '5'keep_one_failed
- A boolean specifying whether to keep all failed releases or just one (the latest failed release), the '--keep-one-failed' flag passed via the CLI takes precedence over this value. If neither CLI nor configuration file value is specified, it defaults to false (i.e. keep all failed releases).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 useparseRelFile
to create the symlink.run_locally:
- Instructions to run locally on your machine in the form of shell commands. Example:
run_locally:
- 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 possibility 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.
maintenance_directory:
- The name of the directory on which the maintenance file will be placed.{deploy_path}/{maintenance_directory}
. The default directory name ismaintenance
maintenance_filename:
- The name of the file that is going to be created in the maintenance_directory. It has to have the.html
extension to be seen in the browser.{deploy_path}/{maintenance_directory}/{maintenance_filename}
. The default filename ismaintenance.html
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:
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.
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:
targets:
- host: myserver-a.com
port: 2222
- host: myserver-b.com
# the rest is the same…
A few things to note here:
-
host
item is required for every target, butport
may be omitted and then it defaults to22
. -
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. -
The log is printed in such a way that messages from several machines get 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.
Docker
Docker images hosted on Docker Hub are no longer up to date, newer versions are published to GitHub's Docker Registry.
Nix
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
Enable/disable maintenance mode
Present a maintenance page to visitors. Disables your application's web interface by writing a {maintenance_filename} file to each web server. The servers must be configured to detect the presence of this file, and if it is present, always display it instead of performing the request.
The maintenance page will just say the site is down for maintenance, and will be back shortly.
To enable maintenance mode run:
hapistrano maintenance enable
Disabling maintenance mode will remove the file from the {maintenance_directory} it can be done with the following command:
hapistrano maintenance disable
Notes
- Hapistrano is not supported on Windows. Please check: Issue #96.
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.