Getting started with manifest files
What is a manifest file?
A manifest files 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 make up your application. If you’re already familiar with manifest files, refer to Building a manifest file.
These are just some examples of the settings you can control with a manifest file:
- Defining sizes and data center region for your servers
- Installing extra packages
- Specifying the version of a component
- Configure application components to share a server
- Customizing component-specific configurations
How do I use a manifest file?
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 that file is checked in you can build your application. Remember to populate the file with appropriate values (see below for examples).
Is my yaml valid?
The manifest file is YAML formatted. You can check its validity at YAML Lint or with this command:
$ ruby -e "require 'yaml'; YAML.load_file('.cloud66/manifest.yml')"
A working example
Change CORS settings
You can use this file to make configuration changes to an existing application. One of these cases is for changing the Cross Origin Resource Sharing (CORS) settings on your web servers.
To get started, open up your manifest.yml file in a text editor and enter the following lines:
production:
rails:
configuration:
nginx:
cors:
origin: '*'
methods: 'GET, OPTIONS'
This is how it works:
production: The top node represents the application environment.
rails: The second level is the application type to which the settings will apply.
configuration: This node contains all the configuration variables for the application type.
nginx: This node allows you to set configurations for your Nginx server.
cors: This node contains all CORS related settings.
origin: Defines the valid origin domains for a CORS request. Can be a wildcard (‘*’), a single origin or a comma separated list of origins.
methods: Defines which HTTP methods are allowed for CORS requests.
headers: Defines which custom headers are allowed for CORS requests.
credentials: Specifies whether requests with credentials are allowed for CORS requests.
Ensure that you save this manifest.yml file under your .cloud66 folder and commit it to your Git repository. You can now deploy a new version of your application with it.
What is CORS?
Cross Origin Resource Sharing is a mechanism that allows many resources (e.g. fonts, JavaScript etc.) on a web page to be requested from another domain outside the domain from which the resource originated.
Force Nginx to update
Although redeploying your application will update its configuration, it will not automatically push down all the changes to your Nginx servers.
To force Nginx configuration changes to be pushed to your servers, we can use a command in the Cloud 66 toolbelt called reconfigure.nginx. Use the following command to push the change (replacing my_app with your application name):
$ cx settings set -s my_app reconfigure.nginx true
This will force your Nginx configuration to be rebuilt during the next redeployment. Once you redeploy, the CORS settings will be updated on your web servers.
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?
- Understand the structure of manifest files.
- Learn more about the power of manifest files with our detailed how-to guide.
- Learn how to use CustomConfig - a powerful tool for configuring the components of your application.
