Custom Config

Using CustomConfig

CustomConfig allows you to edit and modify component configuration templates used by Cloud 66 to configure your servers. This is currently available for Nginx, HAProxy and database configurations, and more configuration templates are forthcoming.

CustomConfig uses the Liquid templating language developed by Shopify and used by many websites. There are many good resources on the web on how to use the Liquid syntax.

Components supported by CustomConfig

CustomConfig templates are available for the following components:

  • HAproxy
  • Nginx
  • MongoDB
  • MySQL
  • PostgreSQL
  • Redis

Accessing CustomConfig

You can access and modify CustomConfig files in two different ways:

  1. Using the Cloud 66 Dashboard
  2. Using CustomConfig git repository

Using the Dashboard

You can find all the CustomConfig templates for your application by:

  1. Logging into your Cloud 66 Dashboard
  2. Clicking on your app to open the Overview
  3. Clicking on ⚙️Application Settings in the right-hand panel
  4. Clicking on the Configuration Files in the sub-nav

You will now see all your configuration files as sub-tabs (as well as your Manifest and other config files depending on your app's particular features).

Add the generic component first

You first need to add a component to your app using the generic configuration before you can set up CustomConfig for it. The system does not support pre-emptive configuration.

Preview a template

To use Nginx as an example, go to your Web Servers group detail page and click CONFIGURE NGINX in the right sidebar. This page will show you the template used to build the Nginx configuration when Nginx is deployed during your application built or reconfigured. Once you’re done with editing your template, you can preview the results by clicking on the Preview button.

See our documentation for more details about CustomConfig for Nginx, HAProxy and databases.

Preview uses dummy data

Preview is generated with dummy data about your server (like the number of cores or the path for different binaries). Refer to our documentation to learn about how the size of your instance affects the number of Nginx workers on your server

Submit template changes

When you are happy with the results, enter a commit message and press the Commit to Server button. This will compile the configuration with real data and push it to all applicable servers in your application. It also performs any post commit steps necessary like reloading Nginx with the new configuration file, putting your changes into effect.

This process takes place in the background and might take some time to complete depending on the number of servers in an application and the nature of the configuration. Also, during the process Cloud 66 will update contents of Custom git repository so after fetching the latest version you can see the history of configuration changes in your own git client tool

You can subsequently see the history of your configuration changes with simple colored diff views alongside dates and comments.

Updates to configuration files and patches

Every so often, Cloud 66 needs to update the base configuration files used for your application to run. When a patch is released, having customized configurations introduces complexities due to the differences in settings. Some of these files are part of CustomConfig, which allows users to customize their configuration files.

When a patch is released, having customized configurations introduces complexities due to the differences in settings. If you don’t have customized content, the patch will be automatically applied.

Warning

Failure to apply configuration updates may lead to unexpected behaviour by your server(s) and application(s).

If we cannot automatically apply the patch, you will be notified and provided with a patch archive. It contains two files - the updated configuration and a patch file. Extract the contents of the archive and download your current configuration from the Cloud 66 UI. With these files ready, run the following command:

patch <current_configuration> -i <patch_file> -o merged_configuration

This will result in a merged_configuration file being created - please ensure that there are no merge errors at this point. Unfortunately we cannot deal with every single use case generically, so it is your responsibility to ensure that the new file conforms with your requirements.

In the absence of merge errors, copy and paste the contents of the merged_template into your CustomConfig form and commit it.

Using CustomConfig git

CustomConfig git is a private git repository available on every application in your Cloud 66 account. This git repository is hosted by Cloud 66 and allows you to modify CustomConfig files for your application using familiar git commands.

If you are familiar with CustomConfig you know how it can be a powerful tool to customize configuration for Nginx or HAProxy.

The easiest way to modify CustomConfig files is through the UI. However if you would like to edit CustomConfig files in your favorite editor or enjoy git merge and flow control features you can use CustomConfig git.

Each application on Cloud 66 has its own private CustomConfig git repository. You can find the URL of this repository under application’s information page. There you will find a URL like this for CustomConfig git:

git@git1.cloud66.com:warmhearted-wondrous-tiger-9262.git

Uploading your SSH public key

Like any other git repository, CustomConfig git requires a public SSH key for authentication. If you are not familiar with how git SSH key authentication works or how to generate your own SSH keys, you can read this great guide by Github: Git SSH key setup.

You can upload your public SSH key at Account / Keys / Public Key when logged into your Cloud 66 account.

Making changes to CustomConfig files

To make a change to a CustomConfig file you need to first clone the application’s CustomConfig git repository locally. Using git commandline this is possible with something like this:

$ git clone git@git1.cloud66.com:warmhearted-wondrous-tiger-9262.git

This will clone the CustomConfig git repository for the first time to your disk under a folder called warmhearted-wondrous-tiger-9262.

Now you can cd to this folder and see the list of files available to edit. By default, CustomConfig git repository contains all the CustomConfig files that are relevant to your application. For example, if you are using HAProxy as load balancer, you will see haproxy.conf as one of the files there. You might also see nginx.conf since you will always have web servers on your application.

Now open the file you want to change in your favorite text editor. Once done, save the file and commit your changes like any normal git workflow:

$ git commit -m "increate nginx pool size"
$ git push origin master

Done!

CustomConfig git workflow

It’s important to know when your changes are going to be pushed to your servers.

Changes made in CustomConfig UI

Any changes made to CustomConfig files in the UI will be applied to CustomConfig git repository as well.

Changing a CustomConfig file in the UI will be pushed to your servers immediately unless there is a merge conflict with what’s in the repository.

Changes made through CustomConfig git

Changes made to CustomConfig git files will NOT be pushed to your servers until the next application deployment. This is prevent unwanted changes go live during a normal git workflow.

What's next?

Previous
Using Failover Groups