Getting started with manifest files

What is a manifest file?

A manifest file - also known as manifest.yml - defines the configuration of your application’s components. It allows you to completely customise the composition of your application and control settings that are not available through the Cloud 66 user interface or Toolbelt.

Manifest file vs service.yml

At first glance, manifest.yml may seem very similar to the service definition in service.yml. However, they do very different things:

Some examples of the settings you can control with a manifest file:

If you’re already familiar with the basics of manifest files, refer to Building a manifest file for a more detailed guide.

Validating YAML

Manifest files are YAML formatted. You can check the validity of your configuration with YAML Lint. If you’d like to learn more about writing YAML, this is a useful beginner’s guide.

Editing manifest files

To access the manifest file for any application:

  1. Navigate to the application detail page for the app in question
  2. Click on Configuration Files in the right-hand panel
  3. Click on the Manifest tab at the top of the main panel

You can now edit the text of your manifest file directly.

Warning

Be cautious when editing the manifest file for any application particularly if it is running in a production environment. A single stray character or space can cause the application to fail to deploy or to deploy in a degraded state.

A working example

In this example we are going to deploy another instance of the simple application we used in our Getting started with Maestro guide. However, instead of using the generic manifest.yml we are going to customise it.

What you’ll need

Before you start, please check you have the following:

An account with your cloud provider of choice. Cloud 66 supports AWS, Google Cloud, Azure, Linode, DigitalOcean, Packet, Rackspace and Cloud A.

Customizing your manifest file

To customize the manifest.yml for your application:

  1. Follow the steps in the Getting Started with Maestro guide but stop before the Deploy your App step.

  2. Click on the Edit config files link above the server configuration box. This will open the “Advanced Deploy” page.

  3. Click on the Configure Manifest tab to access the manifest.yml for your app.

Editing your manifest file

The contents of the file should look very simmilar to this:

docker:
  configuration:
    version: 18.03.0-ce
  servers:
  - server:
      same_as: master
redis:
  configuration:
    version: 4.0.10
  servers:
  - server:
      unique_name: master
      size: s-2vcpu-2gb
      region: lon1
      vendor: digitalocean
      key_name: Your_Digital_Ocean_Project_Name

Next we are going to customise our application in two ways.

Setting a custom name server

In order to force our application to use specific nameservers, we insert the following line into our `manifest.yml’ under the Docker configuration section:

      nameservers: ['8.8.8.8', '8.8.4.4']

Be careful to ensure that the indentation of this new line is correct. It should line up with version under Docker.

Setting a custom Redis version

In this example, we need to use an older version of Redis. To do that, we simply change the version number under redis. We will change to version 4.0.9.

Deploying your application

The end result of both changes should look like this:

docker:
  configuration:
    version: 18.03.0-ce
    nameservers: ['8.8.8.8', '8.8.4.4']
  servers:
  - server:
      same_as: master
redis:
  configuration:
    version: 4.0.9
  servers:
  - server:
      unique_name: master
      size: s-2vcpu-2gb
      region: lon1
      vendor: digitalocean
      key_name: Your_Digital_Ocean_Project_Name

Once you are sure the settings are correct, click the green Deploy button to start the process.

Once your application has been deployed, you can check whether the settings have been applied by accessing your server via SSH using Cloud 66 Toolbelt.

Editing an existing application

The above example applies to a new application, but it is also possible to edit the manifest file of an existing application.

To do this:

  1. From the Cloud 66 Dashboard, open the detail page for your application
  2. Click on Configuration Files in the right-hand panel
  3. Click on the Manifest tab at the top of the main panel

Caution

Editing the manifest file of an existing application may not necessarily result in changes to the deployed instance(s) of that application, even if the application is subsequently redeployed. Read our in-depth guide to understand the complexities around this.

What’s next?