Stackato.yml

Configuration options for Stackato applications can be stored in a stackato.yml or manifest.yml file in the top-level application directory.

The stackato.yml file defines keys and associated values which the stackato client uses to set options that are otherwise passed by the user as command arguments or answers to prompts. Other values are used by the server to install needed packages, or run setup scripts during the staging, post-staging, or pre-running steps in deployment.

Key substitution can be used to insert values from one key into another.

Note

stackato.yml options take precedence over any declared in manifest.yml. Detailed specifications for these configuration files can be found in the stackato-cli source repository:

The following sections describe the available keys and the values that can be assigned to them:

name:

This is the name of the application being pushed. If not specified, the user will be prompted during stackato push to provide a name. The name can also be specified on the command line (eg. stackato push currency-converter).

Example:

name: currency-converter

Note

The application name must be a valid hostname label (i.e. containing only alphanumeric characters and hyphens).

description:

An optional description for the application being pushed, which will appear 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:

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

buildpack:

The Git repository URL for the specific buildpack used to deploy the application. For example:

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

You can use a specific branch by specifying it at the end of the URL using the following format:

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

If unset, Stackato will check to see if the application triggers the detect scripts in any of its built-in buildpacks.

framework:

Specifies the framework type and runtime to be used for deploying the application. If set, this triggers the use of the Legacy Buildpack, which enables the older Stackato v2 / Cloud Foundry v1 staging mechanism.

Applications using language or framework-specific buildpacks do not require these values, and should instead specify the buildpack or rely on the detection scripts of the built-in buildpacks.

type:

The framework to use. Can also be input with the command line option --framework, -f (eg. stackato push --framework python). 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

runtime:

The runtime to use. If not specified, server will select the best option based on available data. Can also be input with the command line option --runtime, -f (eg. stackato push --runtime python32).

Example:

framework:
  type: python
  runtime: python32

document-root:

Overrides the default document-root setting ($HOME) for the web server.

Note

Node.js, Perl, PHP, and Python frameworks only.

Setting a deeper document root directory avoids the problem of exposing supporting files (e.g. stackato.yml) over HTTP.

Example:

framework:
  type: php
  document-root: web

The document-root must always be specified relative to $HOME (/home/stackato/app).

start-file:

Set the main application filename.

Note

Perl and Python frameworks only.

If your application does not use a conventional filename (e.g. app.psgi for Perl, wsgi.py for Python) using this option, possibly in conjunction with document-root, avoids the need to refactor the application for Stackato. For example:

framework:
  start-file: temp.psgi

Or:

framework:
  start-file: temp.py

This value will be 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 as the macro is expanded before the pre-running hooks are run.

app-dir

The directory containing the application code to be pushed to Stackato (if it's not in the top-level directory). This directory becomes the $HOME directory of the application when the application is pushed to Stackato. For example, Java applications will often have a 'target' sub-directory containing the output of ant or mvn builds:

name: sample
framework:
  type: java_web
  runtime: java7
app-dir: target

If required, you can also set document-root in the framework section to specify a sub-directory of the application $HOME to be used as the document root.

To launch multiple applications from multiple sub-directories use a manifest.yml file.

services:

A list of services to create and bind to the application. Each sub key is the name of the service to create / bind, and the associated value is the type of the new service. If multiple services of the same type are needed, list them on separate lines as in the example below.

Note

See the Data Services section for information on how services are bound to applications.

Use stackato services for a complete list of available services. If not specified, the user may be prompted during stackato push.

Example:

services:
  customerdb: mysql
  paymentsdb: mysql

The Stackato client supports key substitution for service names, allowing you to create service names based on the specified application name. For example:

services:
  ${name}-db: mysql

The application name can be set as an option to the stackato push command, overriding the name value defined in stackato.yml. Use this technique when pushing multiple versions of the same application (using different names) if you want them to use separate databases. For example:

name: sample

framework:
  type: node

services:
  ${name}-db: mysql

Using the name specified in stackato.yml, a data service is created to match that name:

$ stackato push -n
Pushing application 'sample'...
Framework:       node
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 an argument to stackato push, 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'...
Framework:       node
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 |
+-------------+---+---------+------------------------------+-------------+

requirements:

Specifies required modules, and allows the installation of additional OS packages.

OS Packages

OS packages can be added in an ubuntu: block within a staging: and/or running: block. Plain strings are treated as package names:

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 beneath the requirements: key:

requirements:
  ubuntu:
    - libfoo-dev

If your account has been given sudo privileges in application containers, you can use arrays to add additional repositories, overriding repository restrictions set by admins.

Example:

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

Language Modules

For the installation of language modules, replacing the requirements.txt file. For Python, pypm: and pip: can be specified:

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

For Perl, ppm: or cpan: can be specified:

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

mem:

The amount of memory to allocate for the application.

Syntax: <int> or <int>M - Memory in megabytes. eg. 256M

Syntax: <int>G or <float>G - Memory in gigabytes. eg. 1.5G or 2G

If not specified, user may be prompted during stackato push. Can also be specified on the command line (eg. stackato push --mem 256M).

Example:

mem: 64M

disk:

The amount of disk space to allocate for the application (minimum 512MB).

Syntax: <int> or <int>M - Disk in megabytes. eg. 768M

Syntax: <int>G or <float>G - Disk in gigabytes. eg. 1.5G or 2G

If not specified, 2GB of disk space is allocated. Can also be specified on the command line (eg. stackato push --disk 768M).

Example:

mem: 3.5GB

instances:

The number of instances to allocate for the application. If not specified, defaults to 1. Can be specified on the command line (eg. stackato push --instances 2).

Example:

instances: 2

Note

If autoscale is enabled (see below) Stackato will initially create the requested number of instances, but can override this number based on the current workload.

autoscale:

The optional autoscale block enables application auto-scaling. It must contain instances and cpu keys, each with min and max values.

Example:

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

Set the enabled key to true to enable autoscaling. If it 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.

placement-zone:

The DEA placement zone to run the app in (optional). Use the stackato placement-zones command to see which placement zones are available on the current target.

url (or urls):

List of URLs mapped to the application. For example:

name: cms-platform

url:
  - blog.example.org
  - exampleblog.com

With the url key set, 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 Stackato will construct a default URL (e.g. "appname.domain.com"). To enable this behavior explicitly (e.g. if you are setting several URLS), use the following special variables:

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

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

See Mapping App URLs for more information.

env:

A map of environment variables to initialize for the application. Each subkey is the name of the variable, with an associated value.

Example:

env:
  HOME_IP_ADDRESS: 127.0.0.1

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

env Attributes

Each environment variable can have attributes which modify the interactive behavior of the stackato client when using the push command. These attributes are set with the following keys:

  • default (string): The value to use if nothing is entered by the user interactively (no default).
  • required (boolean): If set, the variable must have a value (defaults to "false" == "not required").
  • inherit (boolean): If set, the client looks in the local environment for a variable of the same name and takes its value (defaults to "false" == "no inheritance").
  • prompt (string): The prompt to show when the client asks for the variable value (Defaults to "Enter <varname>:").
  • choices (list of strings): If specified, a list of legal values for the variable, to be presented to the user as a menu rather than prompting for a string (no default).

For example:

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

Pushing with the --no-prompt option will fail with the error message "Required variable VAR_NAME not set" if "required" is set but no value is given (via "default", "inherit" or the --env option).

Note

These attributes are only recognized by the stackato client.

processes:

web:

Note

Used with the Legacy buildpack only. When using other buildpacks, create a Procfile in the application's root directory.

Specify a custom command to launch your web application or to pass custom arguments to uWSGI. For example:

processes:
  web: python3.2 app.py

See app.py in:

This key is required when using the generic framework, but is optionally available for all other frameworks.

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

If set to Null ("~"), the application is treated as a worker application and not provisioned with a URL. For example, an application that just runs a background Perl script might look like this:

name: perlwork
framework:
  type: perl
command: perl worker.pl
processes:
  web: ~

A 'command:' value must be present for worker applications.

If the application exists solely to run commands via cron, a dummy command such as 'sleep 365d' should be specified.

The $PROCESSES_WEB and $STACKATO_UWSGI variables can also be used with processes: web:.

$PROCESSES_WEB contains the command that is used to start the web application, if you want to override the default command.

$STACKATO_UWSGI is defined for runtimes using uWSGI (Perl and Python), and it contains the command to start uWSGI with all relevant options. It can be used if you are appending additional uWSGI options to the command.

command:

Used for worker applications to start a background process. Below is an example using the standalone framework:

name: stackato-worker
instances: 1
framework:
  type: standalone
  runtime: ruby18
command: ruby worker.rb

cron:

Commands listed here are added to the crontab file. See the section on Crontab Support for details.

Example:

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

sso-enabled:

Enables or disables Application Single Sign-On (boolean).

ignores:

A list of .gitignore-style patterns. Files and directories in the application directory matching at least one pattern are ignored during "push" and "update".

Example:

ignores: ["tmp", ".git"]

To include all hidden files or folders simply use an empty list.

Example:

ignores: []

If not specified, a default list is used to exclude files and folders not typically required in a deployed application (e.g. the dot files and folders 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

inherit:

This special key has the effect of treating its value as the name of a file to be included into stackato.yml.

Example:

parent.yml:

env:
  COMPANY: The ABC Company

stackato.yml:

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

effect from processing:

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

hooks:

Hooks are commands that are run at various point of the staging and running process of an app. For example:

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 Stackato. This can be useful for building source files (e.g. with 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 will set the STACKATO_HOOK_ACTION variable to "create" if the application is new, or "update" if it detects 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 are only run a single time on push or update.
  • post-staging: Commands run in the root of the app's directory after the staging process is complete. The commands are only run a single time on 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 (i.e. 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:

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

Commands used in the hooks: keys may not include shell metacharacters, such as "&&" for combining commands, "#" for comments, "<", ">" 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.

Also note that if only a single command needs to be run, the list format is not needed and can be included on the same line:

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

drain:

Application log drains can be added to an application when it is deployed by describing them in a drain: block with a drain name and URL:

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

To enable JSON logging, specify the URL separately along with a json: true line:

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

For example:

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

timeout:

Sets the number of seconds for the Health Manager to wait for the application to start (default 60 seconds). Adjust this value upwards (to a maximum of 180 seconds) if your application takes longer than to start. For example:

timeout: 90

This setting can be overridden by the --health-timeout option in stackato push.

min_version:

Sets requirements for the minimum version of the client and server under which the app will run.

client:

The minimum version of the Stackato client needed to manage the app.

To determine the client version, use:

$ stackato version

stackato 0.3.13.0.18

Example:

min_version:
  client: 0.3.13.0.18

server:

The minimum version of the Stackato server needed to run the app.

To determine the server version, use stackato info and use the version number shown in the first line. In this example, the version is 2.4.3:

$ stackato info

ActiveState Stackato v2.4.3

Example:

min_version:
  server: 2.4.3

Key Substitution

The value of any key in stackato.yml can be inserted in other keys using the ${key} syntax. For example:

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

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

A small number of keys are predefined for your use within stackato.yml:

key substitution value
${random-word} A short alphanumeric string of random characters
${target-base} The hostname of the targetted Stackato system, for example stackato-xxxx.local
${target-url} The URL of the targetted API endpoint, for example https://api.stackato-xxxx.local
${ask QUESTION TEXT} Interactively prompt for user input

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

env:
  USER_TOKEN: ${ask Enter user token}

This will prompt the user with "Enter user token" during push and populate a $USER_TOKEN environment variable in the container with the user's response. Everything after the first space up to the closing brace is displayed to the user.

Note

See the services section for an example of variable key substitution for yaml key names.