General Deployment

Applications are typically deployed to Helion Stackato by pushing source code and configuration to the system's API endpoint using the stackato cli client or other clients that use the Helion Stackato or Cloud Foundry API.

The steps for deploying applications will be slightly different depending on the application and its requirements. Instructions for deploying the Helion Stackato sample applications can be found in the README.md file of each app.

Note

In Helion Stackato 3.0 and later (Cloud Foundry v2 API), application deployment is done primarily using Buildpacks. A special, built-in legacy buildpack handles Helion Stackato v2 frameworks for existing application configurations.

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]

Managing Multiple Targets

The Helion Stackato client targets a single location with the command stackato target.

If you need to target two or more instances at the same time, use one of the following methods:

  1. Use the --target <target> option. This sets the specified target for the current command only, and does not set it as the default:

    $ stackato apps --target api.stackato-xxx1.local
    
  2. Use two or more terminals to access multiple targets. Within each terminal, set the STACKATO_TARGET environment variable for the API endpoint URL you want to work with in that terminal. The client will use this URL, overriding any target set with the stackato target command:

    $ export STACKATO_TARGET='api.stackato-xxx2.local'
    

    This target is used until the variable is unset or the terminal is closed. To unset it:

    $ unset STACKATO_TARGET
    

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

Pushing Applications to a Linux DEA

You can deploy your application by running the stackato push command from its directory.

If a manifest.yml configuration file exists in this directory, you can run the stackato push -n command. The command retrieves the application configuration from the YAML file instead of prompting for options.

To Push the Hello World Sample Application (Clojure)

  1. Download the sample application.

  2. From the application directory, push the application to Helion Stackato.

To inspect staging and running logs after deployment finishes, run the stackato logs command.

To Push the Joomla Sample Application (PHP) with an External Service (MySQL)

  1. Download the sample application.

  2. In the application directory, edit the manifest.yml file and add the external service information to the services: block. In the following example, the service name is mysql-dev:

    services:
      ${name}-db: mysql-dev
    
  3. To display the database credentials necessary to configure the application after deployment, add the following command to the post-staging block:

    stackato:
    hooks:
      post-staging:
      - echo $VCAP_SERVICES | json mysql-dev | json -a credentials
    
  4. From the application directory, push the application to Helion Stackato.

    To display the status of the service provisioned for the application, you can run the stackato services command.

Pushing Applications to a Windows DEA

Note

To be able to push application code to a Windows DEA, your Helion Stackato Administrator must ensure that the following requirements are satisfied:

When deploying the application from the root directory of your project's source code, you must specify both the stack and buildpack in the stackato push command:

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

To Push the Orchard Sample Application (C# on ASP.NET)

The following example describes pushing a sample application using the win2012r2 stack and the .NET buildpack.

  1. Download and decompress the sample application.

  2. In the Orchard subdirectory, create a manifest.yml file and add the application name and memory requirements to it:

    name: Orchard
    mem: 128M
    
  3. From the same directory, push the application to Helion Stackato.

Pushing the Contoso University Sample Application (C# on ASP.NET) with an External Service (MSSQL)

The following example describes pushing a sample application from Microsoft Visual Studio using the win2012r2 stack, the .NET Buildpack, and an external MSSQL service.

Important

Ensure that your MSSQL server allows contained database authentication. To enable this option on a standalone server, run the following command:

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

To enable this option on an Amazon RDS instance, see To Enable Contained Database Authentication for an MSSQL-Compatible RDS Instance.

To Prepare the Development Tools
  1. On a Windows machine, download and install Microsoft Visual Studio Community 2015.

  2. Install the Stackato Extensions.

    1. In Visual Studio, click Tools > Extensions and Updates.
    2. On the left panel of the Extensions and Updates dialog box, expand the Online section.
    3. Enter Stackato Extensions into the search box on the right and press Enter.
    4. Under Stackato Extensions for Visual Studio, click Download.
    5. In the Download and Install dialog box, review the license terms and click Install.
    6. At the bottom of the Extensions and Updates dialog box, click Restart Now.
  3. Download and decompress the sample application.

  4. In the C#\ContosoUniversity subdirectory, open ContosoUniversity.sln in Visual Studio.

  5. Install the Stackato MSBuild Tasks and the Stackato .NET SDK.

    1. On the Solution Explorer panel, right-click the project name and then click Manage NuGet Packages.

    2. Enter Stackato into the search box on the right and press Enter.

    3. On the left side of the NuGet: ContosoUniversity panel, click stackato-msbuild-tasks, and then on the right side click Install.

      Note

      If a previous version of the Cloud Foundry MSBuild Tasks is already installed, uninstall it first.

    4. In the Review Changes dialog box, click OK.

    5. On the left side of the NuGet: ContosoUniversity panel, click stackato-dotnet-sdk, and then on the right side click Install.

    6. In the Review Changes dialog box, click OK.

    7. In the License Acceptance dialog box, review the license terms and click I Accept.

To Prepare the Sample Application

You must configure the application to retrieve connection string parameters from environment variables rather than from hardcoded values.

  1. On the Solution Explorer panel, double-click Web.config.

  2. In the editor panel, find the following line:

    <add name="SchoolContext" connectionString="Data Source=(LocalDb)\v11.0;Initial Catalog=ContosoUniversity2;Integrated Security=SSPI;" providerName="System.Data.SqlClient" />
    
  3. Replace it with the following line:

    <add name="SchoolContext" connectionString="{ContosoUniversity-db#connectionString}" providerName="System.Data.SqlClient" />
    
  4. Save Web.config.

  5. To verify that the sample application is configured correctly, right-click the project name and then click Build.

    If the build succeeds, the Build: 1 succeeded message is displayed in the Output panel.

To Push the Sample Application
  1. Configure your API endpoint.

    1. In Visual Studio, click View > Other Windows > Cloud Foundry Explorer.
    2. On the Cloud Foundry Explorer panel, click Add Cloud Foundry Target and in the Add Cloud Foundry Target dialog box enter a Description, the Target URL (your API endpoint), your Username, and your Password, and then click OK.
    3. On the Solution Explorer panel, right-click the project name and then click Publish to Cloud Foundry.
  2. Configure the application.

    1. In the Target dialog box, select the Target that you have configured earlier and click Next.

    2. In the Application dialog box, enter a Name for the sample application, select the dotnet buildpack and the win2012r2 stack, enter 512 into the Memory field, and then click Next.

    3. In the Routes dialog box, enter a Host for the sample application, click the Shared Domain the application will use, and then click Next.

      For example, if the hostname is contosouniversity and the shared domain is 198.51.100.1.xip.io, the application will have the access endpoint contosouniversity.198.51.100.1.xip.io.

    4. In the Services dialog box, select a service.

      • If the ContosoUniversity-db service exists, select it and click Next.
      • If the ContosoUniversity-db service does not exist, click Add New Service and in the Create Cloud Foundry Service Instance dialog box enter ContosoUniversity-db for the Service Name and the name of your Service Type (for example, mssql-dev), and then click OK.
    1. In the Environment Variables dialog box, enter isDebug into the Key field and True into the Value field and click Save Variable, and then click Next.

      Note

      The application will be able to read this key-value pair using the VCAP_APPLICATION environment variable.

  3. Push the application.

    1. In the Environment Variables dialog box, click Finish to push the application to Helion Stackato.

      The output of the push will look similar to the following in the Output panel:

      Starting push...Building with tools version "14.0".
      ...
      Restarting application ContosoUniversity
      ...
      App is staging ...
      ...
      [app] - 02/16/2016 14:13:14: Starting IIS Process
      ...
      Transformation succeeded
      ...
      Push operation finished!
      
    2. To view your application in Cloud Foundry Explorer, right click the application and click View in Browser.

  4. To display the status of the service provisioned for the application, you can run the stackato services command:

    ============== Service Plans ================
    
    +-----------+---------+-------------------------------+--------------+------+--------+----------+---------+--------+------+
    | Vendor    | Plan    | Description                   | Details      | Free | Public | Provider | Version | Broker | Orgs |
    +-----------+---------+-------------------------------+--------------+------+--------+----------+---------+--------+------+
    | mssql-dev | default | Default service               | default plan | yes  | yes    |          |         | usb    |      |
    +-----------+---------+-------------------------------+--------------+------+--------+----------+---------+--------+------+
    
    =========== Provisioned Services ============
    
    +------------+----------------------+-----------+----------+---------+---------+-------------------+------------------+
    | Space      | Name                 | Service   | Provider | Version | Plan    | Applications      | State            |
    +------------+----------------------+-----------+----------+---------+---------+-------------------+------------------+
    | org::space | ContosoUniversity-db | mssql-dev |          |         | default | ContosoUniversity | create succeeded |
    +------------+----------------------+-----------+----------+---------+---------+-------------------+------------------+
    

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:

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.

Note

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

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.

URL Assignment

During stackato push the stackato client assigns URLs for applications as follows:

  1. URLs set with the --url option take precedence

  2. If none is set with --url, URLs specified in manifest.yml are used.

    Note

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

  3. If neither of the above is set, a default URL is generated and assigned using the target-base domain of the system or the domain of the organization (if it has only one domain).

See also Mapping App URLs.

Availability and Placement Zones

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

Availability Zones

Availability zones are Helion Stackato cluster configuration options that help distribute instances of an application across different physical locations, network segments, or racks. This is done to provide high availability in the event of server or network problems.

These zones are configured by Helion Stackato administrators and take effect automatically when multiple app instances are requested. There are no user-facing options.

Placement Zones

Placement zones are groups of DEA nodes which allow for segregation of application instances into different parts of a Helion Stackato cluster, possibly with different physical hardware characteristics or network policies.

DEA nodes are tagged by a Helion Stackato administrator with a placement zone name. Users pushing applications to Helion Stackato can specify which placement zone the application instances are run on by using the --placement-zone option for the stackato push command, or by changing the Placement Zone in the application's Settings view in the Management Console.

The other relevant stackato client commands are:

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

Note

Cron commands are only executed on instance #0 of the app.

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.

Whitespace and Newlines in Environment Variables

To prevent breakage in cron, embedded newlines (\\n) in environment variable values will be replaced with \\\\n when generating the crontab. Any leading and trailing spaces in environment variable values are also stripped.

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.

Note

Application URLs are allocated on a first-come-first-served basis, and are reserved for the user who created the URL.

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.

URL Mapping for Version Cutover

The App Versions feature allows you to deploy new versions of an application without any down time, and provides an easy mechanism to quickly revert to previous versions of the code or configuration.

A manual process is also available which lets you run multiple versions of an application concurrently, using a mapped URL to control which versions receive production traffic.

This technique can also be used to split traffic between multiple application versions for A/B testing.

For example, for an application called customertracker the pushed application name will include a version, build, or revision number, but it is mapped to a production URL as well:

$ stackato apps
Application # Health URLS Services
customertracker-v1 1 RUNNING customertracker-v1.example.com customertracker.example.com mydb

Push the updated code with a new application name:

$ stackato push --as customertracker-v2
$ stackato apps
Application # Health URLS Services

customertracker-v1

customertracker-v2

1

1

RUNNING

RUNNING

customertracker-v1.example.com customertracker.example.com customertracker-v2.example.com

mydb

mydb

Note

In this example, the configured service has the same name, so it is bound to both versions of the application. This will only work if there are no database schema changes or differences in the filesystem layout on a persistent filesystem service. If there are such differences, use distinct data services for the new version.

Map the "production" URL to the new app:

$ stackato map customertracker-v2 customertracker.example.com
$ stackato apps
Application # Health URLS Services

customertracker-v1

customertracker-v2

1

1

RUNNING

RUNNING

customertracker-v1.example.com customertracker.example.com customertracker-v2.example.com customertracker.example.com

mydb

mydb

While both versions of the application are live and mapped to the same production URL, the router will round-robin web requests to this URL between both versions.

This state can be used for A/B testing. To change the distribution of web requests between versions, adjust the number of instances (see stackato instances) each version is running.

To retire one of the apps from the pool, unmap the production URL from the first app:

$ stackato unmap customertracker-v1 customertracker.example.com

The old version is still available (and visible on the non-production URL) in case it is needed for rollback. If everything works as expected with the newer code, delete the old app:

$ stackato delete customertracker-v1
$ stackato apps
Application # Health URLS Services
customertracker-v2 1 RUNNING customertracker-v2.example.com customertracker.example.com mydb

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:

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