Andrew Stacy

Full-Stack Developer

  How I Work

Recent Blog Post

Continuous Deployment with GitLab and GLAD

As a sane web developer I like to automate as much of my repetetive tasks as possible, and when it comes to deploying my code using SFTP or any other more antiquated method, I like to get as far away from them as possible.

At my place of employment we use an in house installation of GitLab Enterprise Edition. GitLab offers a built in Continuous Integration tool and Webhooks that can be configured to trigger on build events.

These Webhooks send a JSON object populated with information about the repository that triggered it to the endpoint (a.k.a. URL).

So, how can we leverage this to trigger and auto deployment? There are a lot of systems available to developers for doing this but we aren't at a place where we need a large system to do so.

After experimenting with various methods for auto deploying I was unable to find anything that matched our needs well. So, I wrote GitLab Auto Deploy (GLAD).

With GLAD you can set it up to receive webhooks and deploy as many different repositories as you would like.

Here is a simple diagram of how it works:

Flow Chart

Deploying MyTest.com

As an example of how to setup automatic deployment with GLAD we will pretend we have a website named MyTest.com that needs to to automatically deploy based on a couple criteria:

  1. It should automatically deploy based on the master branch building successfully.
  2. It should automatically deploy to our test server when a merge request is accepted into our test branch.

In order to deploy with GLAD we'll need to first set up a Git remote on your production and test servers to receive branch pushes and to run a post-receive script to build any assets that our project requires.

For a tutorial on how to set up a Git Remote for deploying to our server, please refer to the tutorial found here: https://gist.github.com/thomasfr/9691385

Setting Up GLAD

When setting up our GLAD server, there are a few place we could install it.

  1. Install onto the same server GitLab is running on (if we self host GitLab).
  2. Install it onto a dedicated server.
  3. Install it on the same server endpoint that your project deploys to.

For the purposes of this tutorial we'll pretend that we are installing this on a server running RedHat Enterprise Linux.

Installation Requirements

In order for GLAD to operate and to be installed properly we will need to install Node with NPM on our server.

Documentation for installing Node on your server operating system can be found at the following link: https://nodejs.org/en/download/package-manager/

Clone the project to your server

I will first navigate to /var and clone the server code from GitHub and navigate into it.

cd /var
git clone https://github.com/AJStacy/git-glad.git
cd git-glad

Install the Server Dependencies

We will also need to install the server dependencies in order for it to run.

npm install

Configure Your GLAD Server

Next we will copy the example server configuration into a new file that the server will read.

cp example.config.json config.json

Now, let's open up our new config file and modify it to handle our deployment criteria (You can find information about the config on the official project readme at https://github.com/AJStacy/git-glad).

{
  "server": {
    "port": 1988,
    "log_level": "warn",
    "timestamp_format": "MM:DD:YYYY - HH:mm",
    "deploy_remote_name": "glad-deploy"
  },
  "repositories": [
    {
      "name": "my-test-com",
      "targets": [
        {
          "branch": "master",
          "deploy_url": "ssh://git@mytest.com/var/repo/my-test-com.git",
          "hooks": {
            "ref": "master",
            "object_kind": "build",
            "build_status": "success"
          }
        },
        {
          "branch": "test",
          "deploy_url": "ssh://git@test.mytest.com/var/repo/my-test-com.git",
          "hooks": {
            "object_attributes.target_branch": "test",
            "object_kind": "merge_request",
            "object_attributes.action": "merge"
          }
        }
      ]
    }
  ]
}

In the above configuration we decided to go with the "server" configuration defaults and just modified the the "repositories" configuration.

Based on our deployment criteria we have 2 targets, the master branch and the test branch.

For our master branch we are deploying to mytest.com and based on the "hooks" it will trigger the deployment when the server receives an "ref" of "master", "object_kind" with a value of "build" and a "build_status" of "success" from the GitLab hooks.

For our test branch we are deploying to test.mytest.com and it will automatically deploy based on the "hooks" of "object_attributes.target_branch": "test", "object_kind": "merge_request" and "object_attributes.action": "merge".

For more information on what data is sent to GLAD by the GitLab webhooks and what kinds of data you can match on for triggering your deployments, refer to the documentation location at need link.

Running the GLAD Server

Now that we have configured our server for deploying our projects we now to to start it up!

There are 2 methods for starting the server.

The first method is mainly used for debugging purposes and can be run with the command:

node index.js

This method will log out all of the server's processes as it receives and attempts to deploy branches. If you were to close your terminal session in this method it would also close the server.

If you are ready to use the server and would like it to run indefinitely in the background, simply append a -d (daemon mode) flag to the startup command like so:

node index.js -d

Your GLAD instance should now be running in the background.

Setting Up Webhooks On GitLab

The last piece of the puzzle is to set up your webhooks on your GitLab project. Remember, you will need to configure them to follow the same criteria we established above in the tutorial.

For instructions on how to set up your GitLab webhooks refer to the documentation at https://gitlab.com/gitlab-org/gitlab-ce/blob/master/doc/web_hooks/web_hooks.md.

You will need to point your webhooks to your server IP address housing the GLAD install with the port number of :1988. An example would look like this:

http://10.11.12.13:1988/

Debugging

At this point the continuous deployment process from GitLab should be automated.

Most problems you may run into regarding this setup is with server permissions, so I would begin there.

If you run into other problems, GLAD keeps details daily logs that you can reference for more information. You can find them from the GLAD server's root folder at ./logs.

Please comment on this article if you need assistance and I will be happy to help.

If you find any bugs, please report them to the official project repo at https://github.com/AJStacy/git-glad.

 Close