HOP On-premises

For the past couple of weeks, we have been working on a new feature in HOP: On-premises deployment. We are happy to announce that it is now available on the latest version of HOP CLI. This post will describe how to get started with this feature and what it is all about.

On the previous version of HOP CLI, users could only choose Amazon Web Services (AWS from now on) as the deployment target. Now, if you open the settings editor using the latest version of HOP CLI, you will also have the option to choose On-premises. Both deployment targets are mutually exclusive (that also applies to profiles), so you can only choose one.

Unlike the AWS deployment target, On-premises does not provision any infrastructure for you. But it provides the necessary files to perform the deployment on-site. That is because HOP can only assume some of the details of your infrastructure or how you deploy your artifacts. Those assumptions include that the deployment machine must be GNU/Linux (with systemd), it has Internet connectivity, and you want to use Docker.

Now let’s see the steps to follow for an On-premises deployment of HOP. When you open the settings editor on the latest version of HOP CLI, you will see a new profile option. The On-premises profile option contains a few configuration settings you can tweak. On the one hand, you have the Persistent data dir, the directory where all the data that we want to persist across container restarts will be stored; on the other hand, you have ssl-termination, where you choose how you want to do SSL termination on the deployment machine. The effects of the Persistent data directory option are clear, but ssl-termination has a very different outcome depending on your choice.

HOP currently offers two alternatives for SSL termination:

• NGINX configuration file: HOP assumes you already have an NGINX instance in place, but does not try to modify its configuration and only provides a suitable configuration file for SSL termination. The only change required in that file is the path to your certificates.
• HTTPS Portal container: A straightforward way to automatically set up SSL termination. HTTPS Portal container uses Let's Encrypt to get certificates and automatically renews them 30 days before they expire. This container is bundled with your deployment Docker Compose file and only runs on the production machine.

Further to this, there are a couple of details that you have to keep in mind when generating a new On-premises project. The Docker Registry configuration setting has a new option named custom. To deploy on-premises, you will need to specify a Docker Registry to store the application container images Continuous deployment also has a new option called on-premises. This setting will only provide a script to create the final application bundle, which contains all the files you will need to run the application (besides the Docker images). And, of course, you will need to choose the on-premises deployment target.

When you generate a new project for on-premises deployment, you will have the same development environment as though you generated an AWS project. Despite some details in some files, the significant differences are in the ci/on-premises and on-premises-files directories. The former is where you will find the application bundle creation script. The latter contains all the files necessary to install the application on the deployment machine. These files include:

• Systemd service: A service file that contains the configuration to start, stop and restart the application service.
• Shell scripts: Three scripts, one for starting the Docker Compose environment, another to stop it, and one that uses the previous two scripts but also does some basic health checks on the application. 
• NGINX configuration file: If you choose NGINX for SSL termination.
• Bash shell configuration files: Two configuration files with some defaults for the system's user that will run the application service.

Apart from these files, you will also have an extra .env.test file. You should store this file securely somewhere, as it is your deployment environment variables (such as database passwords and secrets). These files do not impact your development environment in any way. You can start developing right off the bat using the start-dev.sh script and worry about those files later when you deploy your application system.

When you are ready to deploy, you can read our guide on How to create and install an on-premises HOP Application. It covers both the project creation and installation process. The installation will get you through installing the required packages, setting up the system's user and group, application files, and systemd service, apart from some details about the SSL termination options.

We hope this new feature is handy for your next on-premises Clojure project and don't hesitate to let us know any feedback on how you get on with HOP.