General Deployment¶

Targeting and Authenticating¶

Before deploying an app, the client must first target the API endpoint URL of Helion Stackato. This will generally be the same URL that exposes the Management Console. For example:

$ stackato target api.example.com
Successfully targeted to [https://api.example.com]

Run the stackato login command to authenticate with your username and password:

$ stackato login <username>
Attempting login to [https://api.example.com]
Password: ******
Successfully logged into [https://api.example.com]

Selecting an Organization and a Space¶

If your account is a member of multiple organizations, choose which one you want to operate under:

$ stackato switch-org exampleco

Likewise, if you are a member of more than one space, choose a default space:

$ stackato switch-space devel-example

Pushing Application Code¶

$ stackato push -n --stack win2012r2 --buildpack dotnet

> SQLCmd -S .\sqlexpress  -Q "EXEC sp_configure 'contained database authentication', 1; reconfigure;"

Pushing a Docker Image¶

The stackato push command can also deploy Docker images specified with the --docker-image option. See the Docker Apps section for instructions and restrictions.

Language-Specific Deployment¶

See each of these sections for language-specific deployment details and examples:

• .NET

Configuring Your Application For Helion Stackato¶

Most applications should be able to run under Helion Stackato with only a few changes.

• A manifest.yml file should be added to the root of your application to hold Installation details as well as setup configuration instructions for your app.

• If you want to use Helion Stackato data services, your code will need to use the connection details provided by special environment variables (for example, DATABASE_URL). The code should generally check for the existence of these environment variables, use them if they exist, and otherwise fall back to some default setting.

  For more information, see Data Services.

• Many special environment variables are available during staging and runtime. These can be used in hooks: or application code (to set up databases, filesystem services, web server options, and cron jobs) in places where you would normally use hard-coded paths, credentials, or host-specific values.

  For a complete list, see Environment Variables.

stackato push¶

The stackato push command creates (or updates) applications on Helion Stackato. It negotiates with the API endpoint to reserve application URLs, allocate application instances, provision data services, upload application code, and optionally stage and start the application.

The command will prompt for options or use those specified in a manifest.yml file.

The push command implicitly stages and starts the application unless the --no-start option is used. With this option, applications are pushed in a pre-staged, stopped state where variables can be added (for example, for use in staging hooks). You can then stage and start the application by running the stackato start command or clicking Start in the Management Console.

The client will display staging logs while pushing the application but will generally exit before any application logs are visible. To view the application logs, run the stackato logs command.

Allowed File Types¶

During the push process, Helion Stackato includes only three file types:

• files
• directories
• links

All other special file types are ignored.

Naming and URLs¶

To prevent confusion or collisions, Helion Stackato enforces uniqueness for URLs, application names, and service names:

• URLs (auto-generated or manually mapped) must be globally unique, and are allocated on a "first come, first serve" basis (see URL Assignment).
• Application names must be unique within the scope of the space. Applications deployed in different spaces can have the same name, but the full application URL must be globally unique URL.
• Service names must be unique within the scope of the space. The name given to a service during creation is a pointer to a globally unique string (the actual database name in the system as displayed by STACKATO_SERVICES), so there is no possibility of naming conflicts with services created in other orgs and spaces.

Availability and Placement Zones¶

Helion Stackato has two mechanisms for allocating application instances on particular Droplet Execution Agent (DEA) nodes or groups of nodes:

Application Containers¶

Helion Stackato stages and runs applications within Linux containers on one or more DEA (Droplet Execution Agent) hosts. These containers (managed by Docker) are all copies of a single base image which are modified during staging to add application dependencies.

To inspect this base image to determine what software is pre-installed, or otherwise experiment with the application container, deploy the null application.

Once the app has been deployed, use the stackato client to open an SSH session to the container:

$ stackato ssh -a null
null:~$

From within the ssh session, you can run standard Linux commands. For example, to list the installed packages:

null:~$ dpkg -l

Crontab Support¶

Cron commands can be provided either in a regular crontab file in the root directory of the app, or via the cron: section in manifest.yml (See manifest.yml Options).

The HOME and PATH environment variables, as well as all variables that start with PERL, PYTHON, STACKATO, VCAP, BUNDLE, LEIN, GEM, RACK, RAILS, or RUBY or http are exported to the top of the crontab file. When applicable, the following database related environment variables are also added: DATABASE_URL, MYSQL_URL, POSTGRESQL_URL, REDIS_URL, MONGODB_URL, and RABBITMQ_URL.

This happens after the pre-running hook has executed, so any changes made by those commands will be included in the crontab file.

After setting up environment variables, copy the $HOME/crontab file, and finally the commands from the cron: section in manifest.yml. The resulting file is stored at $STACKATO_APP_ROOT/crontab.

Mapping App URLs¶

Helion Stackato automatically assigns to each application a URL made up of the application's name and the base URL for the system or the current organization. An application named myapp deployed to a Helion Stackato system at api.example.com might be given the URL myapp.example.com.

In addition to this default URL, additional URLs which are assigned to the organization can be set for an application using the stackato map command. The application will respond to requests on the mapped URL, provided a DNS record has been set up resolving to the Helion Stackato external IP or hostname.

For example, to map a URL to an existing application on Helion Stackato:

$ stackato apps

+--------------+---+-----+-------------+-----------------------+------------+--------+
| Application  | # | Mem | Health      | URLS                  | Services   | Drains |
+--------------+---+-----+-------------+-----------------------+------------+--------+
| myapp        | 1 | 128 | RUNNING (-) | myapp.example.com     |            |        |
+--------------+---+-----+-------------+-----------------------+------------+--------+

$ stackato map myapp mydomain.com

+--------------+---+-----+-------------+-----------------------+------------+--------+
| Application  | # | Mem | Health      | URLS                  | Services   | Drains |
+--------------+---+-----+-------------+-----------------------+------------+--------+
| myapp        | 1 | 128 | RUNNING (-) | myapp.example.com     |            |        |
|              |   |     |             | mydomain.com          |            |        |
+--------------+---+-----+-------------+-----------------------+------------+--------+

If DNS is configured correctly, requests to mydomain.com will resolve transparently to myapp.example.com.

URLs can be mapped to multiple applications owned by the same user, which can be useful for A/B testing. Helion Stackato routes requests to the mapped URL randomly between all available app instances.

Using the myapp.example.com example above, you could push myapp-v2 (a more recent revision) then map mydomain.com to that app as well. You can access the specific versions directly using myapp.example.com and myapp-v2.example.com, and use mydomain.com to round-robin between available instances of both versions:

+-------------+---+---------+----------------------+-------------+
| Application | # | Health  | URLS                 | Services    |
+-------------+---+---------+----------------------+-------------+
| myapp       | 5 | RUNNING | myapp.example.com    |             |
|             |   |         | mydomain.com         |             |
| myapp-v2    | 1 | RUNNING | myapp-v2.example.com |             |
|             |   |         | mydomain.com         |             |
+-------------+---+---------+----------------------+-------------+

As you gain confidence with the new revision, you can increase the number of instances of myapp-v2 (phasing that version into production rather than cutting over) and eventually unmap mydomain.com from the original myapp.

$ stackato apps

$ stackato push --as customertracker-v2

$ stackato apps

$ stackato map customertracker-v2 customertracker.example.com

$ stackato apps

$ stackato unmap customertracker-v1 customertracker.example.com

$ stackato delete customertracker-v1

$ stackato apps

Persistent Sessions¶

With multi-instance applications on Helion Stackato, the Router will distribute requests among all instances. Without session management, the end user could access different application instances with each HTTP request instead of connecting to the same instance that started their session.

Cloud-enabled applications should use a shared database (for example, Redis), cache (for example, Memcached), or filesystem as a back-end for session management. Some examples of this approach are:

• Java:
  • Tomcat session manager
  • memcached-session-manager
  • tomcat-redis-session-manager
• Node.js: connect-memcached, a session store that uses Memcached
• PHP:
  • Persistent Sessions (PHP)
  • Memcached session support
• Python: Django "How to use sessions"

The default Helion Stackato router does no special handling of JSESSIONID or SESSIONID cookies.