Building your manifest file

What is a manifest file?

A manifest file allows you to be more explicit about your stack 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 stack. See Getting started with manifest files for an introduction.

For Rails/Rack stacks, 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.

Which environment?

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

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

Which application?

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

ElasticSearch

production:
  elasticsearch:
    configuration:
      version: 0.90.7
      root_disk_size: 100
      root_disk_type: ssd

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

Available settings for a volume are:

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

Note:

You can not change replica_count after GlusterFS added to your stack.

Note:

You can not use glusterfs group or any of its servers in mount_targets.

Note:

Renaming a volume will delete 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:
    configuration:
      version: 2.4.8
      root_disk_size: 100
      root_disk_type: ssd

MySQL

production:
  mysql:
    configuration:
      version: 5.5
      root_disk_size: 100
      root_disk_type: ssd
      engine: percona

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 stacks created since 21st September 2016, you can also specify a comma-seperated 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

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

rails:
  configuration:
    node_version: "6"       # will install latest v6.x.x
    node_version: "6.14"    # will install latest v6.14.x
    node_version: "6.14.4"  # will install specific v6.14.4

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:
    configuration:
      version: 9.3.4
      postgis: true
      root_disk_size: 100
      root_disk_type: ssd

PostGIS

production:
  postgresql:
    configuration:
      postgis:
        version: 2.1.1

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 in your stack.

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
      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']

Rack

A rack application type in 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 in your stack.

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
      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']

Redis

production:
  redis:
    configuration:
      version: 2.6.10
      root_disk_size: 100
      root_disk_type: ssd

Sinatra

For Sinatra use Rack

Load balancers

AWS load balancer

Use a manifest file to customize the AWS load balancer deployed by Cloud 66. These changes will only apply when you create a new load balancer.

Available settings:

production:
  load_balancer:
    configuration:
      httpchk: /

GCE load balancer

Use a manifest file to customize the GCE load balancer deployed by Cloud 66. These changes will only apply when you create a new load balancer.

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

production:
  load_balancer:
    configuration:
      httpchk: /
      balance: CLIENT_IP_PROTO

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 a stack with more than one server, rebuild HAProxy or edit HAProxy CustomConfig.

Available settings (refer to the HAProxy documentation for more information): Server definitions unique_name: Name of the instance size: The size of the instance (Mandatory) region: Digital Ocean’s region (Mandatory) vendor: digitalocean (Mandatory) key_name: Default (Mandatory) 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

Linode Nodebalancer

Use a manifest file to the Linode Nodebalancer deployed by Cloud 66. These changes will only apply when you create a new load balancer.

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

production:
  load_balancer:
    configuration:
      httpchk: /
      balance: leastconn

Rackspace load balancer

Use a manifest file to customize the Rackspace load balancer deployed by Cloud 66. These changes will only apply when you create a new load balancer.

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

production:
  load_balancer:
    configuration:
      balance: LEAST_CONNECTIONS

CloudA load balancer

Use a manifest file to customize the CloudA load balancer deployed by Cloud 66. These changes will only apply when you create a new load balancer.

production:
  load_balancer:
    configuration:
      balance: ROUND_ROBIN

Which server?

Every application defined in the manifest file must be bound to a server. However, if you’d like configurations to apply to all servers in an application type, you don’t need to specify a server type. Servers can be deployed specifically to host that application, be shared between multiple applications (eg. Rails and MySQL on the same server) or be an external server (eg. 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 in a stack.

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 applications. 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 applications 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 an application (like using your own MySQL or AWS RDS for example), you can define that server as external.

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

production:
  mysql:
    server: external

Important!

You are required to specify a server for application types, 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 stack. 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 stack. If you want to avoid this, you can set restart_on_deploy to false.

Default values for each process type are:

Specify additional LiveLog files

Each application type supports the additional partial configuration to add custom live log files for that application type:

production:
  rails:
    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