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. See Getting started with manifest files for an introduction.
For Rails/Rack applications the path for manifest.yml
is:
<application-root>/.cloud66/manifest.yml
The .cloud66
folder must in the root of your source code & repo.
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.
The structure of a Manifest file
Manifest files are made up of blocks of settings that define the infrastructural elements of your application. This includes both the “hardware” (virtual or real servers) and the “software” (such as the version of Docker your application uses).
A typical block of settings will contain come combination the following:
- Environment (optional) - the environment to which the settings apply
- Component settings (required) - the settings for the component being configured (e.g. MySQL or an AWS Load Balancer)
- Server definition (optional) - the specifications for the server used by the component defined in the settings above
- Custom log files (optional) - each component can be configured to use custom LiveLog files
You can also control and customize some other elements in your Manifest including:
- Environment variables - you can set environment variables for your app
- Background processes - you can customize the Linux signals used to control your background processes
Important
It is vital that you understand the limits and caveats of manifest settings. Please read our reference guide before you start creating your own manifest files.
Environment settings
The (optional) environment setting allows you to use the same manifest.yml
for multiple applications with different environments. Some examples are:
- production
- staging
- development
You can also use your own custom environment names in your Manifest file.
Applying settings across all environments
If you would like your 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.
Component settings
The (mandatory) component settings define how a component is configured. The Manifest file currently supports the following components (click on any component name for a detailed doc):
- ElasticSearch
- Gateway
- GlusterFS
- Load balancers
- Memcached
- MongoDB
- MySQL
- Nginx
- Node version
- PostGIS
- PostgreSQL
- Redis
- Sinatra
- Rails
- Rails health checks
Note
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.
Server definitions
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 simple server definition:
rails:
servers:
- server:
unique_name: app
These are the parameters that the server section can take:
Option | Applied on | Description | Clouds |
---|---|---|---|
availability_zone |
Build-only ⓘThis setting only applies when the app is first built (or cloned) or when new servers are added. |
Availability zone of the server instance in AWS EC2 region. | AWS |
key_name |
Build-only ⓘThis setting only applies when the app is first built (or cloned) or when new servers are added. |
The name of the API key for the cloud account where the server will be built. You can see (and edit) all your cloud API key names in your Dashboard Settings. This is used when an account has multiple keys for a given cloud vendor. The default value is Default . |
All |
region |
Build-only ⓘThis setting only applies when the app is first built (or cloned) or when new servers are added. |
The data center region where the server will be built. | All |
root_disk_size |
Build-only ⓘThis setting only applies when the app is first built (or cloned) or when new servers are added. |
Default size of root disk (in GB) for servers used by application. Default value is 50. | AWS, Azure, GCE |
root_disk_type |
Build-only ⓘThis setting only applies when the app is first built (or cloned) or when new servers are added. |
Disk type, accepted values being ssd and magnetic . Default is ssd . |
AWS, GCE |
size |
Build-only ⓘThis setting only applies when the app is first built (or cloned) or when new servers are added. |
The size of the server instance to be created. | All |
subnet_id |
Build-only ⓘThis setting only applies when the app is first built (or cloned) or when new servers are added. |
ID of the AWS subnet in which you would like to create your servers. | AWS |
unique_name |
Build-only ⓘThis setting only applies when the app is first built (or cloned) or when new servers are added. |
A unique name for this server (Required if you are specifying a server type) | All |
vendor |
Build-only ⓘThis setting only applies when the app is first built (or cloned) or when new servers are added. |
Cloud vendor where the server will be built. Valid values: aws , azure_rm (use azure for older Azure accounts), clouda , digitalocean , googlecloud , hetzner , linode , ovh , packet , rackspace , and vultr |
All |
Important
All of the servers for an application must belong to a single cloud vendor and region. Different applications may use different clouds, but a single application cannot use multiple clouds.
A more complex server example
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
You can deploy to one of your Registered servers via manifest settings. The server must be registered before deployment.
Option | Applied on | Description | Clouds |
---|---|---|---|
address |
Build-only ⓘThis setting only applies when the app is first built (or cloned) or when new servers are added. |
IP address of the server, only applicable to Registered Servers | Registered servers |
unique_name |
Build-only ⓘThis setting only applies when the app is first built (or cloned) or when new servers are added. |
Unique name for the registered server | Registered servers |
Example of registered server
redis:
servers:
- server:
unique_name: redis-main
address: 123.123.123.123
Shared Servers
You can share a server between two components. This allows you to, for example, use a server for both your front-end app and the database server backing it.
Option | Applied on | Description | Clouds |
---|---|---|---|
same_as |
Build-only ⓘThis setting only applies when the app is first built (or cloned) or when new servers are added. |
The name of another server definition in the same manifest file. This component will use the same server when it is deployed. | All |
Example of shared server
rails:
servers:
- server:
unique_name: my_rails_app
vendor: aws
key_name: Default
region: us-east-1
size: m3.medium
mongodb:
servers:
- server:
same_as: my_rails_app
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):
mysql:
servers:
- server: external
Custom LiveLog files
You can add custom live log files for each component. For example:
rails:
configuration:
custom_log_files: ["/tmp/mylog/*/*.log"]
…or
docker:
configuration:
custom_log_files: ["/tmp/dockerlog/*/*.log"]
postgresql:
configuration:
custom_log_files: ["/tmp/your-other-log.log"]
For more information about LiveLogs and additional examples, please see the LiveLogs help page.
Environment variables
You can add environment variables to your manifest files, either globally or per environment. For example:
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.
Detailed examples of Manifest files
In this example we’re defining a MySQL server with all the bells and whistles:
mysql:
groups:
default:
configuration:
version: 8.0
root_disk_size: 1000
root_disk_type: ssd
engine: percona
iam_instance_profile_name: mysql-perms
custom_log_files: [ "/tmp/mysqllog/*/*.log" ]
servers:
- server:
unique_name: mysql-main
vendor: aws
key_name: Default
region: us-east-1
size: m3.medium
subnet_id: subnet-40000000
availability_zone: us-east-1c
In this example we’re defining a Rails app and an accompanying MySQL instance, and applying these settings only in the production environment:
production:
rails:
configuration:
ruby_version: 2.7.2
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
servers:
- server:
unique_name: rails-main
vendor: aws
key_name: Default
region: us-east-1
size: m3.medium
subnet_id: subnet-40000000
availability_zone: us-east-1c
mysql:
groups:
default:
configuration:
version: 8.0
Notice that we haven’t specified a server for the MySQL instance in this YAML. In cases like this the Cloud 66 Dashboard will prompt you to specify a server during the deployment process, and that server will be installed with MySQL V8.0.
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:
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: