Building your manifest file

Overview

A manifest file allows you to be more explicit about your application composition and control settings that are not usually available through the user interface or Cloud 66 toolbelt.

The file describes the setup of the components that run your application. See Getting started with manifest files for an introduction.

For Rails/Rack applications, place a file called manifest.yml in a folder named .cloud66, that is in turn located in the root of your source code and checked into your repository.

Once you’re ready, start by going through each section below to build your manifest file.

Problems upgrading?

If you explicitly set the version of any component in your manifest file, we will respect that setting even if it conflicts with other system changes or upgrades (for example upgrading Ubuntu). If you are having trouble upgrading any component of your application, remember to check your manifest file to ensure you have not previously locked the version of that component or one of its dependents.

Which environment?

The first level of your manifest file is the environment - this allows you to use the same manifest.yml for multiple applications with different environments. Some examples are:

You can also use your own custom environment names in your manifest file.

Applying settings across all environments

If you would like you a manifest setting to apply to all environments, you can simple drop the root level environment node from your YAML. This will ensure a component is always provisioned, regardless of environment.

Which component?

Next, select which component you would like to specify settings for. You can choose from the following:

ElasticSearch

production:
  elasticsearch:
    groups:
      my_main:
        configuration:
          iam_instance_profile_name: elastic-perms
          version: 0.90.7
          root_disk_size: 100
          root_disk_type: ssd
      my_spare:
        configuration:
          version: 0.90.7

Gateway

Note

The gateway should be defined and open before you can use it in manifest.

production:
  gateway:
    name: aws_bastion
	username: ec2-user

GlusterFS

The version of GlusterFS currently offered via the Cloud 66 Add-in is not supported by Ubuntu 18.04. To use this add-in please ensure that all of your application components are installed on servers running Ubuntu 16.04.

Available settings for a volume are:

After you change the volume list, you need to redeploy your application for new configuration be applied to your application.

Notes

- You can not change replica_count after GlusterFS added to your application.
- You can not use glusterfs group or any of its servers in mount_targets.

Warning

Renaming a volume will actually delete that volume and create a new one.

production:
  glusterfs:
    configuration:
      version: 3.7
      replica_count: 2
      mount_targets: ['app','redis']
      volumes:
      - volume:
          name: images-data
          mount: "/mnt/images"
          access_control:
            read: ['web', 'api']
            write: ['web']
      - volume:
          name: videos
          mount: /mnt-data/videos
          access_control:
            read: ['web']
            write: ['web']

Memcached

production:
  memcached:
    configuration:
      memory: 1024
      port: 11211
      listen_ip: 127.0.0.1

MongoDB

production:
  mongodb:
    groups:
      my_mongo:
        configuration:
          version: 2.4.8
          root_disk_size: 100
          root_disk_type: ssd
      spare_mongo:
        configuration:
          version: 2.4.8

MySQL

production:
  mysql:
    live-db:
      configuration:
        version: 5.7
        root_disk_size: 100
        root_disk_type: ssd
        engine: percona
        iam_instance_profile_name: mysql-perms
    upgrade:
      configuration:
        version: 8.0
        root_disk_size: 100
        root_disk_type: ssd
        engine: percona
        iam_instance_profile_name: mysql-perms

Nginx

production:
  rails:
    configuration:
      nginx:
        cors: true
        extra_build_arguments: "--add-module=/path/to/module"
        perfect_forward_secrecy: true # deprecated

CORS configuration

If required, you can also specify the allowed origin (as ‘*’ or a single origin) and methods. For applications created after September 2016, or if you have updated your application to use the latest NGINX configuration, you can also specify a comma-separated list of origins, headers, and whether to allow credentials for CORS.

production:
  rails:
    configuration:
      nginx:
        cors:
          origin: '*'
          methods: 'GET, OPTIONS'
          headers: 'Custom-Header, Another-Header'
          credentials: true

Node version (for Rails applications)

We automatically install the latest release of Node version 6.x.x when we set up your Rack/Rails application servers. You can control which version is installed by editing the manifest file for any Rails application as follows:

rails:
  configuration:
    node_version: "12"       # will install latest release of v12.x.x

rails:
  configuration:
    node_version: "12.18.3"  # will install specific v12.18.3

If you need a newer version of Node, you can install one using the same method above. We support any version of Node that is supported by our version manager (which itself supports the Node distribution list).

Applying changes

To apply changes to the Node version you need to update your manifest file, then deploy-with-options and select the Apply Ruby/Node upgrades option.

PostgreSQL

production:
  postgresql:
    groups:
      live-data:
        configuration:
          iam_instance_profile_name: psql-perms
          version: 9.3.4
          postgis: true
          root_disk_size: 100
          root_disk_type: ssd
      spare-data:
        configuration:
          version: 9.3.4

PostGIS

Rails

A Rails application type in the manifest file gives you fine control over things like the Ruby version or the server the rails application is deployed on.

Important

In order to use a vpc_id, you must provide subnet_id for all servers used by your application.

production:
  rails:
    configuration:
      ruby_version: 2.2.0
      asset_pipeline_precompile: true
      do_initial_db_schema_load: false
      reserved_server_memory: 0 #default value
      passenger_process_memory: 200 #default value
      memory_allocator: jemalloc # malloc is default
      locked_passenger_version: 4.0.59
      activeprotect:
        whitelist: 123.123.123.123,234.234.234.234
        http_ban_rate: 2000 # Default
      vpc_id: vpc-64872001
      root_disk_size: 100
      root_disk_type: ssd
      nameservers: ['8.8.8.8', '8.8.4.4']
      iam_instance_profile_name: rails-perms

Rack

The manifest file gives you fine control over things like the Ruby version or which server the application is deployed on.

Important

In order to use a vpc_id, you must provide subnet_id for all servers used by your application.

production:
  rack:
    configuration:
      ruby_version: 1.9.3
      do_initial_db_schema_load: false
      reserved_server_memory: 0 #default value
      passenger_process_memory: 200 #default value
      memory_allocator: jemalloc # malloc is default
      locked_passenger_version: 4.0.59
      activeprotect:
        whitelist: 123.123.123.123,234.234.234.234
      vpc_id: vpc-64872001
      root_disk_size: 100
      root_disk_type: ssd
      nameservers: ['8.8.8.8', '8.8.4.4']
      iam_instance_profile_name: rack-perms

Rails (Rack) deployment health checks

These checks define tests to confirm whether your application has been successfully deployed, and to mark a deployment as “failed” if any do not pass. They have the following options:

All of these are optional. For more details on health checks please read our how-to guide.

Example:

    rails:
    	configuration:
    		health:
    			protocol: 'https'
    			host: '127.0.0.1'
    			port: 4430
    			endpoint: '/'
    			accept: ["200", "300-399"]
    			timeout: 30

Redis

production:
  redis:
    configuration:
      version: 5.0.5
      root_disk_size: 100
      root_disk_type: ssd
      iam_instance_profile_name: redis-perms

Sinatra

For Sinatra use Rack

Load balancers

AWS load balancer

You can use your Manifest file to customize the AWS load balancer deployed by Cloud 66.

Available settings:

    production:
      load_balancer:
        configuration:
          httpchk: /
          wait_after_adding_servers: 30 # default is 0
          wait_after_removing_servers: 10 # default is 0         
          alb_ssl_policy: ELBSecurityPolicy-FS-1-2-2019-08 # default
          elb_ssl_policy: ELBSecurityPolicy-TLS-1-2-2017-01 # default

GCE load balancer

You can use your Manifest file to customize the GCE load balancer deployed by Cloud 66.

Available settings (refer to the GCE documentation for more information):

    production:
      load_balancer:
        configuration:
          httpchk: /
          balance: CLIENT_IP_PROTO
          wait_after_adding_servers: 30 # default is 0
          wait_after_removing_servers: 10 # default is 0

HAProxy

Use a manifest file to configure and define your HAProxy load balancer deployed by Cloud 66. These changes will be either be applied when you redeploy an application with more than one server, rebuild HAProxy or edit HAProxy CustomConfig.

Available settings (refer to the HAProxy documentation for more information):

Server definitions

Configuration

    production:
      load_balancer:
        servers:
        - server:
            unique_name: bananana
            size: 1gb
            region: ams2
            vendor: digitalocean
            key_name: Default
        configuration:
          httpchk: HEAD / HTTP/1.1\\r\\nHost:haproxy  #default value
          balance: roundrobin #default value
          errorfile_400: /etc/haproxy/errors/400.http
          errorfile_403: /etc/haproxy/errors/403.http
          errorfile_408: /etc/haproxy/errors/408.http
          errorfile_500: /etc/haproxy/errors/500.http
          errorfile_502: /etc/haproxy/errors/502.http
          errorfile_503: /etc/haproxy/errors/503.http
          errorfile_504: /etc/haproxy/errors/504.https
          wait_after_adding_servers: 30 # default is 0
          wait_after_removing_servers: 10 # default is 0

Linode Nodebalancer

Use a manifest file to the Linode Nodebalancer deployed by Cloud 66.

Available settings (refer to the Linode documentation for more information):

    production:
      load_balancer:
        configuration:
          httpchk: /
          balance: leastconn
          wait_after_adding_servers: 30 # default is 0
          wait_after_removing_servers: 10 # default is 0

Rackspace load balancer

Use a manifest file to customize the Rackspace load balancer deployed by Cloud 66.

Available settings (refer to the Rackspace documentation for more information):

    production:
      load_balancer:
        configuration:
          balance: LEAST_CONNECTIONS
          wait_after_adding_servers: 30 # default is 0
          wait_after_removing_servers: 10 # default is 0

Which server?

Every component defined in the manifest file must be bound to a server. However, if you’d like configurations to apply to all your servers, you don’t need to specify a server type.

Servers can be deployed specifically to host a single component, be shared between multiple components (e.g. Rails and MySQL on the same server) or be an external server (e.g. using an external database).

Here is an example of a server definition:

production:
  rails:
    servers:
    - server:
      unique_name: app

These are the parameters that the server section can take:

Important

Only a single cloud vendor and region is supported for servers used by an application.

production:
  rails:
    servers:
      server:
        unique_name: app
        vendor: aws
        key_name: Default
        region: us-east-1
        size: m3.medium
        root_disk_size: 100
        root_disk_type: ssd
        subnet_id: subnet-40000000
        availability_zone: us-east-1c

Deploy to your own server

production:
  rails:
    server:
      unique_name: frontend
      address: 123.123.123.123

Shared Servers

You can share a server between two components. This could be in cases like using the same server for both your Rails app and the MySQL server behind it.

Each shared server definition specifies the name of another server definition in the manifest file for which the components will then share the physical server:

production:
  rails:
    server:
      same_as: *another_existing_servers_unique_name*

External Servers

If you would like to use an external server for a component (like using your own MySQL or AWS RDS instance, for example), you can define that server as external.

External server definitions specify that the component is hosted on a server external to Cloud 66. This is not a valid target for your main application (e.g. rails) but may be appropriate for another component (e.g. MongoDB):

production:
  mysql:
    server: external

Important

You are required to specify a server for components, whereas configurations are optional.

Specify environment variables

You can add your environment variables to your manifest files.

Here is an example:

production:
  environment_variables:
    SOME_VARIABLE: value
    ANOTHER_ONE: another_value
    THIRD_ONE: AUTO_GENERATE
    LONG_ONE: AUTO_GENERATE_15

If you need to auto generate a value, you can use the AUTO_GENERATE keyword. It generates a 10 character long random string unless you specify the length after it: AUTO_GENERATE_15 which generates a 15 character random string.

Environment variables set in your manifest file will only apply during the initial build of your application. Please refer to our documentation on environment variables if you’d like to set them beyond this point.

Any environment variable that is generated by the result of the code analysis (like database addresses) will override any value specified in the manifest file. In other words, you cannot specify a value like MYSQL_ADDRESS in your manifest file as it will be ignored.

Processes

Background processes can be deployed and managed by Cloud 66. Any process in a Procfile will be picked up, deployed and monitored by the system.

If you would like more flexibility over the signals used to control the processes, you can use the procfile_metadata section. Here is an example:

production:
  procfile_metadata:
    worker:
      stop_sequence: ttin, 120, term, 5, kill
    web:
      restart_signal: usr1
      stop_sequence: usr1, 30, kill
    nsq:
      restart_on_deploy: false

In this example, a process called worker is stopped using a TTIN signal first. After waiting for 120 seconds, if the process is still running, a TERM signal will be sent. If it is still running after 5 seconds, it will be killed.

As for web or custom_web processes, you can specify a restart_signal which will be sent to the process serving web. This is useful for web servers that can do “phased” or zero-downtime restarts.

All processes restart during each redeployment of the application. If you want to avoid this, you can set restart_on_deploy to false.

The default values for process signals depend on which web server and/or process manager you are using.

For the default signals for web servers, click the links below:

For non-web processes:

Specify additional LiveLog files

Each component supports the additional partial configuration to add custom live log files for that component. For example:

production:
  rails:
    configuration:
      custom_log_files: ["/tmp/mylog/*/*.log"]

…or

production:
  docker:
    configuration:
      custom_log_files: ["/tmp/mylog/*/*.log"]

For more information about LiveLogs and additional examples, please see the LiveLogs help page.

Need help with deployments?
Contact Support
More Questions?
Join the Slack Channel