Deplorable Repo Deployer

Deplorable is a simple & small daemon that deploys your code.

What is it?

Deplorable is a background process and HTTP server. It accepts web hooks from your favorite collaborative version control service^* whenever you push to a particular branch, fetches the most recent code from your repository, and "builds" it using the Nix expression in your repository (in default.nix).

When can I use it?

Now!

Where can I use it?

It has been tested to work running as a systemd service on NixOS, but it should work anywhere a compiled Rust program can run, listen on a TCP socket, and invoke the Nix package manager. This should include any Linux distribution, as well as OS X, and potentially Windows and BSD if you're willing to put in some elbow grease.

You don't have to use systemd to run it. You can use SysVinit scripts, a tmux/screen session, launchd, upstart... you do you. Systemd is nice because deplorable will likely end up running with a fairly low PID number, and that's apparently important for some reason.

Why would I use it?

Suppose you're at a large institution that has a policy that makes it hard to point subdomains at Netlify or GitHub pages, but easy to get public IPv4 addresses and host web sites on your workstation, a server in the basement, or an on-premise virtual machine. Deplorable can help you get the experience of using these services without the headache of arguing with anyone about whether hosting a website on GitHub does or does not violate internal policies or whether internal policies should change.

Alternatively, suppose you want

• Automatically deploying static web sites using static site generators such as Jekyll or Hugo on your own server.

• Automatically deploying static web sites using your own framework, or some other framework not supported by major static site hosts.

• That's pretty much it? Any other reason you might have to keep the most recent version of your code compiled on some computer somewhere.

How do I use it?

Great question!

You'll need five things:

1. (Optional, but actually required for now) a working Rust compiler and the Rust package manager Cargo. You only need this if you want to compile deplorable from source. Howoever, at present, you almost certainly need to compile it from source. If you're using Nix to compile deplorable, this will already be taken care of for you.

2. Some basic dependencies including libcurl and openssl. If you're using Nix to build deplorable (see below), this is already taken care of for you. See how nice a meta!

3. One or more GitHub repositories you want to deploy automatically.

4. A computer connected to the Internet that can accept web hooks (a public IP address is ideal, but tools such as ngrok and smee can help if you're behind a NAT or are otherwise unable to listen directly for TCP connection on the public Internet).

5. The Nix package manager (instructions here. Note that you do not need eleveated privileges to install or use the Nix package manager.

Build

First, get the source code. There are various ways you can do this, but let's use Git 'cause why the heck not:

$ git clone git://github.com/alevy/deplorable
$ cd deplorable

Next, you have a choice. You can build deplorable with Rust's cargo or you can build deplorable with Nix (which, in turn, will invoke Rust).

$ cargo build --release
# outputs to $PWD/target/release/deplorable

or

$ nix build
# outputs to $PWD/result/bin/deplorable

Configure

Deplorable uses a YAML (meaning it can also be JSON) configuration file to determine which repositories it expects to receive web hooks from and which credentials (if any) it should use. The configuration file has a top-level "repos" key that resolves to a list of repository objects. The key for each repository will correspond to it's webhook path.

Each repository object MUST include at least the following entries:

• repo: the full GitHub repo name, i.e. {owner}/{repo}.
• reference: the full reference to watch and deploy from, including the refs/heads/ prefix. Typically, this might be something like refs/heads/master or refs/heads/staging.
• out: a relative or absolute path where the repo should be compiled to. Whichever user is running deplorable must be able to write to this location.

Optionally, a repository object may also contain:

• secret: the shared GitHub webhook secret used to authenticate the GitHub webhook. It is not necessary to configure a shared secret, but recommended to avoid spurious builds.
• token: an GitHub OAuth token that permits access to the repository if it is private.

The following example shows a configuration for two totally non-existant repositories, one public, one private.

repos:
  # Site 1 is in a public repo
  site1:
    repo: myuser/mysite1
    reference: refs/heads/master
    out: /var/www/site1
    secret: mysecretkey1
  # Site 2 is in a private repo, so it needs a token to access
  site2:
    repo: myuser/mysite2
    reference: refs/heads/beta
    out: /var/www/site2
    secret: mysecretkey2
    token: AAAAAAAAAAAAAAAAAAAAAAAAAAAAAAAAAAAAAAAA

Run

Run the damn thing!

$ target/release/deplorable -c YOUR_CONFIG_FILE.yaml -l 0.0.0.0:1337
Listening for web hooks on 0.0.0.0:1337

If you'd like to expose deplorable over TLS and/or on ports 80 or 443, you might consider reverse proxying, e.g., through NGINX or Apache.

Setup Web Hooks

Follow GitHub's guide to setting up a webhook for your repository.

For each repository, the "Payload URL" is:

http://YOUR_IP_OR_DOMAIN_NAME:1337/REPO_KEY_FROM_CONFIGURATION

Select application/json for the content type and ensure the secret matches the one in your configuration file. Finally, you only need to activate Push events, which is the default. Other events will be ignored anyway.

FAQs

1. Why is it called deplorable?

It helps you "deploy" things, and I needed to name the repository something. Please don't read into it.

^* as long as your favorite collaborative version control service is GitHub.