Manifest.yml Options ¶

The manifest.yml file defines keys and associated values which the Helion Stackato client uses to set application configuration options that you can otherwise pass as arguments or as answers to prompts during the stackato push command. The server uses additional values to install necessary packages or to run setup scripts during the staging, post-staging, or pre-running deployment steps.

The following sections describe the available keys and the values that can be assigned to them. Some keys must be declared within a stackato: block. These keys are listed in the stackato: section.

Contents

Key Substitution ¶

You can use key substitution to insert values from one key into another using the ${<KEY>} syntax. For example:

name: example-app
env:
  MY_NAME: ${name}

This example defines a $MY_NAME environment variable with the value example-app.

A few keys are predefined for your use within manifest.yml:

Key Substitution	Value
`${random-word}`	A short, alphanumeric string of random characters
`${target-base}`	The hostname of the targeted Helion Stackato system, for example `stackato-xxxx.local`
`${target-url}`	The URL of the targeted API endpoint, for example `https://api.stackato-xxxx.local`
`${ask <QUESTION>}`	An interactive prompt for user input

The special ${ask} variable instructs the stackato client to prompt the user for a value when an application is pushed and displays optional query text. For example:

env:
  USER_TOKEN: ${ask Enter user token}

This example prompts the user with Enter user token during the push and populates a $USER_TOKEN environment variable in the container with the user's response. All text after the first space up to the closing brace is displayed to the user.

For an example of variable key substitution for YAML key names, see the services: section.

app-dir:¶

This key specifies the directory that contains the application code to be pushed to Helion Stackato (if it is not located in the top-level directory). This directory becomes the $HOME directory of the application when the application is pushed to Helion Stackato. For example, Java applications often have a target sub-directory that contains the output of ant or mvn builds:

name: sample
app-dir: target

Note

You can launch multiple applications from multiple sub-directories using the manifest.yml file.

applications:¶

This key specifies a list of options corresponding to individual apps to be pushed. Each sub-key must match the name of the directory where the files for the app are contained. For example:

---
applications:
  web:
    name: springweb
    instances: 1
    memory: 512
  worker:
    name: springweb-helper
    instances: 1
    memory: 64

In this example, the two keys web: and worker: match the sub-directories (named web and worker) of the directory that contains the manifest.yml file.

You can use the shortcut . if the application code is in the top-level directory with manifest.yml:

applications:
  .:
    name: singleapp
    buildpack: https://github.com/cloudfoundry/ibm-websphere-liberty-buildpack.git
    instances: 1
    memory: 512

buildpack:¶

This key specifies the Git repository URL for the specific buildpack used to deploy the application. For example:

name: java-app
memory: 512M
buildpack: https://github.com/heroku/heroku-buildpack-java.git

You can specify a branch by appending it to the end of the URL. For example:

buildpack: https://github.com/cloudfoundry/heroku-buildpack-nodejs.git#profile

You can also specify a tag. For example:

buildpack: https://github.com/heroku/heroku-buildpack-java.git#tagname

If not set, Helion Stackato will check whether the application triggers the detect scripts in any of its built-in buildpacks.

command:¶

This key is used by worker applications to start background processes. The following example uses the standalone framework:

name: stackato-worker
instances: 1
command: ruby worker.rb

depends-on:¶

This key specifies the order in which apps are started and stopped. Use this key when deploying multiple applications from a single manifest.yml file. An app with the depends-on: option will be pushed only after the apps listed below have been pushed and are running on the server.

For example, if you want web to start before worker, add depends-on: worker in the web: section:

applications:
  web:
    depends-on: worker
    name: springweb
    instances: 1
    memory: 512
  worker:
    name: springweb-helper
    instances: 1
    memory: 64

Note

If an app is stopped or restarted, the process happens in the reverse order.

description:¶

This key specifies the description for an application which appears in the Management Console application views and in the stackato app [appname] output. For example:

description: Python application for converting between various currencies

Use quoted strings if you have a long description that spans multiple lines. For example:

description: "This demo installs Drupal to Helion Stackato by using \'drush\'
  in post-staging hooks. Very little code is pushed by the client,
  only the scripts used to configure Drupal on Helion Stackato."

disk: (DEPRECATED)¶

Note

The disk key is deprecated. Use disk_quota to specify disk limits. You may still use disk. However, if you specify both keys, disk_quota will be used.

Important

The minimum value for --disk is 512MB. The maximum value is 2GB. This is a per-instance limit.

This key specifies the amount of disk space to allocate for an application (minimum 512MB). If the key is not specified, 2GB of disk space is allocated.

Syntax:

<INT> or <INT>M in megabytes, for example: disk: 768M

<INT>G or <FLOAT>G in gigabytes, for example: disk: 1.5G or disk: 2G

The key can also be specified from the command line, for example: stackato push --disk 768M.

disk_quota:¶

The amount of disk space to allocate for the application, specified using M for megabytes or G for gigabytes. For example, disk_quota: 1024M.

docker_image:¶

This key allows you to specify a Docker image from the Docker Hub or from specific Docker registry servers: You can specify this key in a number of different ways, for example:

With or without a tag:
```
docker_image: django:1.8-python2
```
Using the namespace for a particular user or organization:
```
docker_image: cloudfoundry/lattice-app
```
Using a fully-qualified URL for a particular registry server (omitting the protocol portion):
```
docker_image: registry.example.com/user/docker-app:latest
```

Using the <user>:<pass>@<host> format for credentials:

docker_image: myName:myPass123@reg.example.com/myName/myApp

drain:¶

This key allows you to add application log drains to a deployed application by describing them in a drain: block with a drain name and URL. For example:

drain:
  drain_name: protocol://host.domain.tld:port/

To enable JSON logging, specify the URL on a separate line in addition to a json:true line. For example:

drain:
  drain_name:
    url: protocol://host.domain.tld:port/
    json: true

You can specify multiple drains in the same key. For example:

drain:
  mytestdrain: udp://logs.papertrailapp.com:12346/
  otherdrain:
    url: tcp://logs.papertrailapp.com:12345/
    json: true

env:¶

This key specifies a map of environment variables to initialize for an application. Each sub-key is the name of a variable, with an associated value. For example:

env:
  HOME_IP_ADDRESS: 127.0.0.1

Note

Avoid using this key for values which should not be stored in plain text, such as API keys and passwords.

env: Attributes ¶

Note

These attributes are recognized only by the Helion Stackato client.

Each environment variable has attributes which can modify the interactive behavior of the Helion Stackato client when using the push command. These attributes are specified using following sub-keys:

default: (string): The value used if nothing is entered by the user when prompted (no default).
required: (boolean): If set, the variable must have a value (defaults to "false" == "not required").

Note

If required: is set but no value is specified (via the default or inherit attributes or the --env option), pushing with the --no-prompt option will fail with the error message "Required variable *VAR_NAME* not set".

inherit: (boolean): If set, the client looks in the local environment for a variable with the same name and takes its value (defaults to "false" == "no inheritance").
prompt: (string): If set, the prompt that is displayed when the client requests the value of the variable (defaults to "Enter <varname>:").
choices: (list of strings): If set, a list of legal values for the variable to be presented to the user as a menu rather than a prompt for a string (no default).

Example:

env:
  MY_SPECIAL_VAR:
    default: "development"
    required: y
    inherit: y
    prompt: "What type of deployment?: "
    choices:
    - "development"
    - "testing"
    - "staging"
    - "production"

framework: (DEPRECATED)¶

Note

framework: has been deprecated. You may use this key to trigger the Legacy Buildpack, which enables the older Helion Stackato 2.x / Cloud Foundry 1.x staging mechanism. However, applications that use language- or framework-specific buildpacks should specify the buildpack key or rely on the detection scripts of the built-in buildpacks.

document-root:¶

Note

This sub-key works only with the Node.js, Perl, PHP, and Python frameworks.

This sub-key overrides the default document-root setting ($HOME) for the web server. document-root: must always be specified relative to $HOME (/home/stackato/app).

You can avoid exposing supporting files (for example, manifest.yml) over HTTP by setting a deeper document root directory. For example:

framework:
  type: php
  document-root: web

runtime:¶

This sub-key specifies the runtime to use. If the key is not specified, the server will select the best option based on available data. For example:

framework:
  type: python
  runtime: python32

This sub-key can also be specified from the command line, for example: stackato push --runtime python32.

start-file:¶

Note

This sub-key works only with the Perl and Python frameworks.

This sub-key specifies the main application filename. You can avoid refactoring your application for Helion Stackato if your application does not use a conventional filename (for example, app.psgi for Perl or wsgi.py for Python) by using this sub-key (optionally in conjunction with document-root:). For example:

framework:
  start-file: temp.psgi

Or:

framework:
  start-file: temp.py

The specified value is used by the PROCESSES_WEB and STACKATO_START_FILE environment variables. Any changes to STACKATO_START_FILE at runtime will not change the value of PROCESSES_WEB because the macro is expanded before the pre-running hooks are run.

type:¶

This sub-key specifies the framework to use. The Legacy Buildpack supports the following frameworks:

aspdotnet
django
generic
grails
java_ee
java_web
lift
node
otp_rebar (Erlang)
perl
perlcgi
php
play
python
rack
rails3
sinatra
spring
standalone
wsgi

This sub-key can also be specified from the command line, for example: stackato push --framework python.

inherit:¶

Note

inherit: must be placed at the beginning of the file and cannot be nested within another tag. name: must be specified in both the parent and child manifest files.

This key treats its value as the name of a file to be included in manifest.yml, for example:

The env: key is specified in parent.yml:

name: example-app
env:
  COMPANY: The ABC Company

The inherit: key is specified in manifest.yml:

name: example-app
inherit: parent.yml
memory: 64M

As a result, manifest.yml inherits the env: key from parent.yml:

name: example-app
env:
  COMPANY: The ABC Company
memory: 64M

instances:¶

This key specifies the number of instances to allocate for an application, for example: instances: 2. If the key is not specified, it defaults to 1.

This key can also be specified from the command line, for example: stackato push --instances 2.

Note

If autoscale is enabled, Helion Stackato initially creates the requested number of instances. However, it can later override this number based on its current workload.

memory:¶

This key specifies the amount of memory to allocate for an application. If not specified, the user may be prompted for a value during stackato push.

Syntax:

<INT> or <INT>M in megabytes, for example: mem 256M

<INT>G or <FLOAT>G in gigabytes, for example: mem 1.5G or mem 2G

The key can also be specified from the command line, for example: stackato push --mem 256M.

name:¶

This key specifies the name of the application being pushed, for example: name: currency-converter. If the key is not specified, the user will be prompted to provide a name during stackato push.

Note

The application name must be a valid hostname label (it must contain only alphanumeric characters and hyphens).

placement-zone:¶

This key specifies the DEA placement zone to run the app in.

Note

To determine which placement zones are available on the current target, use the stackato placement-zone command.

services:¶

This key specifies a list of services to create and bind to an application. Each sub-key is the name of the service to create or bind, and the associated value is the type of the new service.

If you need to launch an application that must attach to an existing user-provided service instance, specify only the name of a service.

Note

If only the name of a service is specified in a services: block, Helion Stackato will look for an existing service with the specified name instead of creating a new service (which requires additional keys).

If multiple services of the same type are needed, list them on separate lines, for example:

services:
  customerdb: mysql
  paymentsdb: mysql

If the key is not specified, the user may be prompted for a value during stackato push.

Note

For a complete list of available services, use the stackato services command. For more information on how services are bound to applications, see the Data Services section.

To bind to an existing User-Provided Service instance, specify only the service name without a service type. Prepend each item in the block with a hyphen + space (YAML list syntax). For example:

services:
- prod-oracle-db

To create service names based on the specified application name, you can use key substitution. For example:

services:
  ${name}-db: mysql

To push multiple versions of the same application (using different names) that will use separate databases, you can specify the application name as a stackato push option, overriding the name: value defined in manifest.yml. For example:

name: sample
services:
  ${name}-db: mysql

A data service is created to match that name using the name specified in manifest.yml:

$ stackato push -n
Pushing application 'sample'...
Runtime:         <framework-specific default>
Application Url: sample.stackato-pjw3.local
Creating Application [sample]: OK
Binding service [sample-db]: OK
...
Starting Application [sample]: ...OK

If you specify a new name for the application as a stackato push argument, a new service with a matching name is created rather than binding to the existing sample-db service:

$ stackato push sample-2 -n
Pushing application 'sample-2'...
Runtime:         <framework-specific default>
Application Url: sample-2.stackato-pjw3.local
Creating Application [sample-2]: OK
Binding service [sample-2-db]: OK
...
Starting Application [sample-2]: ..OK

$ stackato apps

+-------------+---+---------+------------------------------+-------------+
| Application | # | Health  | URLS                         | Services    |
+-------------+---+---------+------------------------------+-------------+
| sample      | 1 | RUNNING | sample.stackato-pjw3.local   | sample-db   |
| sample-2    | 1 | RUNNING | sample-2.stackato-pjw3.local | sample-2-db |
+-------------+---+---------+------------------------------+-------------+

sso-enabled:¶

This key enables or disables Application Single Sign-On (boolean).

stackato:¶

The following Helion Stackato-specific options must be placed in a stackato: block, indented as sub-keys. For example:

applications:
  .:
    name: celery-demo
    buildpack: https://github.com/hpcloud/stackato-buildpack-python.git
    memory: 128
    stackato:
      autoscale:
        enabled: true
        instances:
          min: 4
          max: 10
        cpu:
          min: 30
          max: 85
      env:
        CELERY_ENV:
          default: crisper
      processes:
        web: celeryd
      requirements:
        pypm: [celery]
      hooks:
        pre-running:
        - sudo cp $HOME/fstab /etc/fstab
        - sudo mount /dev/shm
      min_version:
        server: 0.9.0.143
        client: 1.0

autoscale:¶

This key enables application auto-scaling. It must contain instances and cpu keys, each with min and max values. For example:

stackato:
  autoscale:
    enabled: true
    instances:
      min: 4
      max: 10
    cpu:
      min: 30
      max: 85

To enable autoscaling, set the enabled key to true. If the value is set to false, the other autoscaling parameters will be ignored and the top-level instances value will be used to set a specific (static) number of instances.

cron:¶

This key adds the listed commands to the crontab file. For example:

stackato:
  cron:
  - PLUGH=xyzzy
  - "*/1 * * * * env > $HOME/env"

For more information, see the Crontab Support section.

hooks:¶

This key specifies commands that are run at various points of the staging and running process of an app. For example:

stackato:
  hooks:
    pre-staging:
    - python prestagingsetup.py
    post-staging:
    - python manage.py syncdb --noinput
    - python manage.py migrate --noinput
    pre-running:
    - python prerunsetup.py

There are four stages at which hooks can be run:

pre-push: Commands run on the local system before pushing the code to Helion Stackato. This can be useful for building source files (for example, using make) or performing configuration steps that need to be done on the local system before the application code can be pushed. Commands are executed between application creation (when the URL and application resources are reserved) and the actual upload of the local code.

The client specifies the STACKATO_HOOK_ACTION variable to create if the application is new, or to update if it detects that the application already exists. You can use this variable to run hooks differently in either context.

pre-staging: Commands run in the root of the app's directory before the staging process is started. The commands run only once, during push or update.

post-staging: Commands run in the root of the app's directory after the staging process is complete. The commands run only once, during push or update.

pre-running: Commands run in the root of the app's directory after staging is complete and before the app is started. The commands are run sequentially in the order listed each time an app is started or restarted.

Hook processing ends and staging aborts if a command returns a nonzero exit status (if the command fails). You can suppress this behavior by prefacing the command with "-" to force staging to proceed despite failures. The "-" must be included in a quoted command string. For example:

stackato:
  hooks:
    post-staging:
    - "-python manage.py syncdb --noinput"

Note

Commands used in hooks: keys may not include shell metacharacters, such as && for combining commands, # for comments, or <, >, or | for I/O redirection.

If you need shell functionality such as metacharacters, signal trapping, or forcing zero exit status, wrap your command in a script.sh file and use sh +x script.sh as your hook command.

If you need to run a single command, the list format is not needed and can be included on the same line.

Example:

stackato:
  hooks:
    post-staging: python staging.py
    pre-running:  python running.py

ignores:¶

This key specifies a list of .gitignore-style patterns. Files and directories in the application directory matching at least one pattern are ignored during push and update, for example: ignores: ["tmp", ".git"].

To include all hidden files or directories, use an empty list, for example: ignores: [].

If the key is not specified, a default list is used to exclude files and directories not typically required in a deployed application (for example, the dot files and directories of various source code control systems).

The default list contains the following:

~*/, .git/, *.svn/, *.hg/, *CVS/, _FOSSIL_.fos, *.bzr, *.cdv, *.pc, *RCS, *SCCS, *_MTN, *_build, *_darcs, *_sgbak, *autom4te.cache, *blib, *cover_db, *~.dep, *~.dot, *~.nib, *~.plst

min_version:¶

The sub-keys of this key specify the requirements for the minimum version of the client and server on which an application runs.

client:¶

This sub-key specifies the minimum version of the Helion Stackato client needed to manage an application. For example:

stackato:
  min_version:
    client: 3.2.1

To determine the client version, you can use stackato version.

server:¶

This sub-key specifies the minimum version of the Helion Stackato server needed to run an application. For example:

stackato:
  min_version:
    server: 3.6.0

To determine the server version, use stackato info. The the version is displayed on the first line of the output.

processes:¶

web:¶

Note

This sub-key works only with the legacy buildpack. If you use other buildpacks, create a Procfile in the application's root directory.

This sub-key specifies a custom command for launching a web application or for passing custom arguments to uWSGI. For example:

stackato:
  processes:
    web: python3.2 app.py

This sub-key is required when using the generic framework, but it is optionally available for all other frameworks. For more information on app.py usage, see bottle-py3 and cherrypy-p3.

If defined, this process is expected to launch a HTTP server bound to host 0.0.0.0 and port $PORT.

If set to Null (~), the application is treated as a worker application and not provisioned with a URL.

In the following example, an application runs solely a background Perl script:

name: perlwork
command: perl worker.pl
stackato:
  processes:
    web: ~

Note

For worker applications, a command: value must be included.

If an application exists solely to run commands via cron: you should specify a dummy command such as *sleep 365d*.

You can also use the $PROCESSES_WEB and $STACKATO_UWSGI variables with processes: web:. If you want to override the default command, you can use $PROCESSES_WEB which contains the command used to start the web application.

$STACKATO_UWSGI is defined for runtimes using uWSGI (Perl and Python) and it contains the command that starts uWSGI with all relevant options. You can use $STACKATO_UWSGI to append additional uWSGI options to the command.

requirements:¶

This key specifies required modules and allows the installation of additional OS packages.

Language Modules¶

For installation of language modules, this key overrides the requirements.txt file.

For Python, you can specify pypm: and pip::

stackato:
  requirements:
    pypm:
    - tornado
    - pymongo
    pip:
    - pycurl

For Perl, you can also specify ppm: or cpan::

stackato:
  requirements:
    ppm:
    - CGI::Application::PSGI
    - Plack::Builder

stackato:
  requirements:
    cpan:
    - CGI::Application::PSGI
    - Plack::Builder

OS Packages¶

You can add OS packages in a ubuntu: block to the staging: and running: blocks . Plain strings are treated as package names:

stackato:
  requirements:
    staging:
      ubuntu:
      - libfoo-dev
    running:
      ubuntu:
      - libfoo
      - some-app

To add the OS requirements to both the staging and running phases, add the ubuntu: block directly to the requirements: key:

stackato:
  requirements:
    ubuntu:
      - libfoo-dev

If your account has sudo privileges for application containers, you can use arrays to add additional repositories, overriding repository restrictions set by administrators. For example:

stackato:
  requirements:
    staging:
      ubuntu:
      - ["ppa:gophers/go"]
      - golang-stable
    running:
      ubuntu:
      - libfoo

timeout:¶

This key specifies the number of seconds for the Health Manager to wait for the application to start (60 seconds by default), for example: timeout: 90. If your application takes too long to start, adjust this value upwards (to a maximum of 180 seconds).

You can override this setting using the --health-timeout option in stackato push.

url:¶

This key specifies the list of URLs mapped to the application. For example:

name: cms-platform
url:
- blog.example.org
- exampleblog.com

If the key is set, Helion Stackato assigns the specified URLs to the application being pushed. The mapped URL must use a domain name that has been assigned to the current Space.

If the key is not set, and only one domain is assigned to the Space, Helion Stackato creates a default URL (for example, appname.domain.com). To enable this behavior explicitly (for example, if you are setting up several URLS), use the following special variables:

url:
- ${name}.${target-base}

If the key is explicitly set to empty (url: []), Helion Stackato deploys the application as a worker, without a URL.

For more information, see Mapping App URLs.