Chappy

Chappy is the simplest way to deploy websites using GitHub webhooks.

Define a project and deployment script to run and Chappy will listen for changes to your GitHub repo and deploy automatically. It's perfect for small scale deployments like a single DigitalOcean server ❄️

Quick Start Guide

Download

Operating System
Linux x64
MaxOS (10.7 and above)
Windows x64
Windows x32

There are more options for different types of operating system in the build folder.

Installation

To get started, download the correct executable for your operating system, and move it to a directory in your $PATH. For example on Linux x64:

$ mv chappy-linux-amd64 chappy
$ chmod +x chappy
$ sudo mv chappy /usr/local/bin/chappy

❓ Questions? You can read the step by step installation instructions for Linux, Mac and Windows.

Creating a project

The next step is to create a projects file which will define the webhooks you want to serve for one or more repos. First, create an empty projects.json file in your home or www directory. Let's define a project namedMyWebsite that will run a deploy script located in /var/www/MyWebsite/deploy.sh.

[
  {
    "name": "MyWebsite",
    "branch": "master",
    "script": "/var/www/MyWebsite/deploy.sh",
    "secret": "<SECRET>"
  }
]

🔐 To make sure only GitHub can run your webhook, each project should have a unique secret string. You can quickly generate a random 32 character string by running chappy secret, or use a random password generator - either way, make sure to replace <SECRET>.

Creating a deploy script

Your deploy script should be an executable script (make sure to chmod +x deploy.sh). At it's most basic form, it should run git pull, to update the repo with the latest changes. The example below installs any new dependencies with composer and npm and rebuilds assets using gulp.

#!/bin/bash
git pull
composer install
npm install
gulp --production

Arguments with the event details are passed to the script, which can be used to run commands dynamically. There are some more advanced deploy script examples on the Deploy Script page that show how to use this feature.

You can now start Chappy using

$ chappy start

⚙ Check the CLI page to see a list of commands available, how to configure the IP and port that Chappy runs on and enable other settings like hot reloading the projects file or serving over HTTPS.

Creating the webhook

Add a new Webhook to your GitHub repo, which can be found in Settings -> Webhooks -> Add webhook.

• By default, the payload URL will be your server IP, port 9000 and then your project name. i.e. http://123.456.0.1:9000/MyWebsite.
• A content type of application/json is recommended but it can be any.
• The secret should be the secret string you defined in projects.json.
• The event you need to listen to is just the push event.

Testing

⏰ Coming Soon - Chappy will log to a file letting you know if anything's wrong - and listen for the GitHub ping event to skip having to make a test commit.

To test everything runs successfully, make a test commit or pull request to the main branch ("Beep, Boop! - Testing Chappy 🤖" will do just fine).

If the webhook finishes without errors and your script runs correctly, then congrats 🎉! If there are errors, please read the Troubleshooting page or submit an issue. 🕷

Running forever

To run Chappy in the background, follow the step by step guide for:

• Linux
• Mac
• Windows

License

• A lot of webhook logic taken from the webhook library by adnanh.
• Logo by Arsenty from the Noun Project.

---

Who's a good boy?