Deploying Apps

An application (app) is any code implementing your organization's business logic. Apcera can work with apps written in a number of languages and frameworks. This section explains how to deploy, run, and monitor apps in Apcera. It also provides tips for troubleshooting problems with deployments. Also see the related tutorials.

Deploying an app from source code

You can deploy an app from source code to your Apcera cluster by running apc app create <app name> in the directory where your source code resides, or specifying the source code directory with the --path option.

For example, assuming you've downloaded the Apcera sample applications from GitHub, you can deploy a simple website by creating a new application from the example-static sample application, as follows:

apc app create website --path ~/sample-apps/example-static --batch --start
Packaging... done
Creating package "website"... done
Uploading package contents... done!
[staging] Subscribing to the staging process...
[staging] Beginning staging with 'stagpipe::/apcera::static-site' pipeline, 1 stager(s) defined.
[staging] Launching instance of stager 'static-site'...
[staging] Downloading package for processing...
[staging] Validating an index.htm or index.html file exists
[staging] Staging is complete.
Creating app "website"... done
Start Command: ./start_nginx
Waiting for the application to start...
App should be accessible at ""

To view the running site, open the link displayed on successful app deployment ("). You should see a web page that displays "Hello, World".

In response to apc app create, APC first creates a compressed archive (TGZ file) of all the files in the folder specified by --path (or the current working directory, if not specified) and uploads it to the cluster to create a new package. You can exclude files from being included in the TGZ by add a .apcignore file to the application directory.

The process of taking application source code and converting it to a runnable workload is called staging. Each application you create from source code is staged via a particular staging pipeline. In most cases, APC will automatically select the appropriate staging pipeline for your workload type (see Automatic staging pipeline detection). In this case, APC selected the static-site staging pipeline to stage the application, as the source folder contains an index.html file.

See Deploying a Static Web Site for a complete tutorial on deploying a static web site. Also see Tips for deploying specific app types.

You can also create applications from Docker images or existing packages.

Setting application properties

When you create or update an application you can specify properties on the application, such as the application's start command, or environment variables to set on the container.

The apc help app create produces a list of this command's options. Here are a few of the more important ones:

Option Behavior
--path PATH Path to the app (default: current path)
--staging NAME Staging Pipeline to use (default: auto-detected)
--encrypt Encrypt the volume the container data is mounted on. See Encrypting application data volumes.
--allow-egress Allow the app open outbound network access
--env-set Sets an environment variables on the app. Multiple values can be supplied by invoking multiple times (e.g. --env-set 'HOME=/usr/local' --env-set 'PATH=/usr/bin:/opt/local')
--pkg-env Like --env-set, but for app's package
--start-cmd String that specifies the command to start the application. See Application start command for details.
--start Start the app after deploying it
--restart Restart behavior for instances. Valid values are "no", "failure", or "always". For applications the default value is "always"; for Docker jobs, the default is "no". See Application Restart Modes for more information.


  • --staging deals with staging pipelines. These are important in Apcera, but in most cases, Apcera knows which one to use. You don't have to tell it. Working with Staging provides more information about staging pipelines.
  • Apps are by default prevented from direct internet access. --allow-egress tells Apcera that it's OK for the deployed app to access arbitrary IP addresses (for example, public websites).
  • --env-set sets environment variables on the deployed app. pkg-env sets them on the package that the app comes from.

You can use an application manifest to set most of the above command options as well.

Application start command

An application's start command is a string that specifies the commands to start the job's main process. The app's main process must block and be run in the foreground. If the process is non-blocking or is started in the background, then Apcera assumes the job instance has failed and will attempt to restart it according to the app's restart mode.

By default, the app process is run as the Linux user "runner" (UID 99) and group "runner" (GID 99). This user owns the /app directory in the container, but otherwise has limited permissions. The runner user can also invoke sudo without a password, if necessary, for example:

apc app update my-app --start-cmd 'sudo some-command'

You can specify the UID and GID to run the process as with the --user and --group parameters. For example, the following creates a new application whose process is started as the user "root" and group "root":

apc app create myapp --user root --group root

You can concatenate commands in the start command, and call one or more scripts, for example:

start_cmd: 'chmod 755 /app/classes/ && ./'

Exposing Ports on a Job

A route maps an endpoint to an exposed port on an application. If no ports are exposed then you can't map any routes to that app. To manually expose a port on a application, use the apc app update command's --port-add parameter, for example:

apc app update your-app --port-add 4567

By default, if your application is not listening on the specified port then the application will fail to start (see Port Health Check). You can override this behavior by including the --optional flag when adding the port:

apc app update your-app --port-add 4567 --optional

After this update the Health Manager will not monitor port 4567 on your application as part of its port health checks. If an application stops accepting connections on the optional port, automatic restart is not supported.

Maintaining logs of application events

For a detailed discussion of logging, see Working with Logs.

Anything written to standard out (stdout) or standard error (stderr) is captured in your app logs. This means that you can log from anywhere in your application code with a simple output statement. Apcera keeps the last 1,500 lines of app logs available for inspection using apc app logs. For long-term storage, you can add log drains to your apps to send all messages to a collection endpoint. If you don't currently operate a syslog-compatible log collector, we recommend using a 3rd party log archive and analysis service such as Splunk or Papertrail.

Tailing app logs

Like the Linux tail -f command, Apcera's apc app logs <app-name> displays recent logs and leaves the session open for realtime logs to stream in. By viewing a live stream of logs from your app, you can gain insight into its behavior and debug problems.

You can also tail an application's logs in the web console.

Logs tab in web console

By default, apc app logs retrieves 20 log lines. You can fetch up to 1,500 lines using the --lines or -l option: $ apc app logs -l 200

Setting up syslog drains

Adding drain endpoints to an app enables you to configure sinks to store syslog-formatted logs externally. First configure the service or your server to be able to receive syslog packets from Apcera. Then add the service's syslog URL (which contains the host and port) as a syslog drain using

apc drain add <drain-url> --app <app-name>

RFC5424 specifies the format of drain log messages.

The drain feature supports only TCP drain endpoints. You can discover all of an app's drains by running apc drain list --app <app-name>.

Encrypting application data volumes

When creating an application you can optionally encrypt the data volume on which the job's file system is mounted. This is often referred to a "encryption at rest". This feature prevents access to the data on the encrypted volume if, for example, a virtual machine were decommissioned and its drive space re-assigned to another app, or if a hard disk were removed from a cluster and installed in a new environment. This feature does not protect against application-level security failures, such as a SQL injection attack.

Data volumes are encrypted using LUKS (Linux Unified Key Setup). When the application is started its data volume is encrypted using a one-time, random password. To encrypt an application's volume you pass the --encrypt flag to the apc app create command, as shown below:

apc app create my-encrypted-app --encrypt --path ~/src/myapp

You can also use the --encrypt flag when creating a capsule with apc capsule create or creating an application from a Docker image using the apc docker run command.

Note: Application data volumes are ephemeral and destroyed when the application is stopped. To have persistent encrypted storage you can bind the application to an encrypted APCFS or encrypted SMB service.

You can automate the enforcement of application data encryption using policy. See policy for data at rest encryption.

Updating app properties

To update an app's properties you use the apc app update command. For example, the following adds an environment variable named HOME to the app and sets its allocated memory to 2GiB:

apc app update myapp --env-set HOME=/usr/local --memory 2048

Some property changes require a restart of the application, which APC will prompt for.

Update requires job restart

Automatically restart and proceed? [Y/n]:

The following table lists which properties can be updated on an app and whether a restart is required:

allow-egress Allows open outbound network access on the app Yes
cpus Milliseconds of CPU time per second of physical time (default: Uncapped) Yes
disk Amount of disk space to allocate, in MB (default: 1GiB) Yes
env-set Sets environment variables on the app Yes
env-unset Unsets environment variables on the app Yes
group Specifies the GID to run the process as. Yes
instances Updates the number of instances of the app (default: 0) No
memory Amount of memory to allocate, in MB (default: 256MiB) Yes
name The app's local name. No
netmax Amount of maximum network throughput to allow (ceiling), in Mbps (default: 0Mbps, Uncapped) Yes
netmin Amount of network throughput to allocate (floor), in Mbps (default: 5Mbps) Yes
network Virtual network to join, leave, or enable/disable network multicast or broadcast on. Yes
pkg-add Adds the package specified by NAME to the app, installed at PATH (default: /) Yes
pkg-delete Removes the package specified by NAME from the app Yes
port-add Exposes a port No
port-delete Removes an exposed port No
start-cmd Modifies the start command of the app. See [] Yes
timeout Number of seconds the system waits for an app to start before triggering a failure Yes
user Specifies the UID to run the process as. Yes

All the above properties can be updated on other jobs in Apcera, such as capsules, docker images, and so forth.

For start commands on Windows, you need to use double quotes. See this topic for an example.

Changing job names

A job's fully-qualified name (FQN) includes a namespace (/prod/sites) and a local name (myapp). In the 2.6.0 release of the Apcera Platform and later, neither the namespace nor the local name of a job's FQN may be changed.

Excluding files from packages

By default, APC bundles all files in the application source directory (specified by the --path parameter) into a tarball that's uploaded to the cluster to create the associated application package. You can exclude files from being included in the tarball by placing a .apcignore file in the application's root directory. This file accepts .gitignore-style patterns to match which files or folders to exclude from the package.

This feature also works when creating a package or creating a stager with the apc package create and apc stager create commands. Below are some example .apcignore file entries.

# Ignore all logfiles and tempfiles.

# Ignore Java .class files

# Ignore compiled Object files, Static and Dynamic libs (Shared Objects)


This section describes some common problems and how to deal with them.

Debugging staging errors

Check the error messages. If staging fails, (for example, if a package dependency isn't present, or is missing for a Rack-based app), Apcera tells you why.

A common staging problem is adding a route to an app that should not have one.

By default, Apcera tries to stage apps as webapps, but a non-webapp cannot have a route. The --disable-routes option of apc app create disables automatic route and port allocation.

If a port is exposed on an app, then Apcera expects the app to be listening on that port. If Apcera can't talk to the app over the exposed port and the port is not created with the --optional option, then Apcera assumes the app has failed.

Use apc route delete to remove an unwanted route.

For additional information on troubleshooting application staging errors, see Stager degugging.

Check the app's logs

If the app is running, apc app logs tails live logs as they stream in, giving you access to stdout and other app logs.

Access the app's shell

The command apc app console clones the app and its service bindings into a capsule, then connects to it so you can run shell commands (for example, rake db:migrate).

$ apc app console rubyapp
Creating a capsule for app/job "rubyapp"... done
Creating binding to "outside"... done
Starting the capsule... done
Waiting for the capsule to start... done

A console is a cloned copy of your app that runs in a capsule. When you access the console (capsule) instance, you are dropped in at the command line as user root (UID 0 inside the container).

App instances, on the other hand, run code as Linux container user runner (UID 99 inside the container). The runner account can (optionally) invoke passwordless sudo. For example, the start_command: field in an app manifest can be sudo <command>. However, this is not recommended.

When you access an app console, although the app instance's start command is shown to the developer (but not executed), executing that start command will result in possibly different results from the same command in an app instance (root vs. runner).

To emulate the app instance context when using an app console, run the following command in the app console instance before issuing the start command: su - runner.

App health

The Apcera health manager monitors the state of applications and ensures that started applications are indeed running with the correct versions and numbers of instances. Apcera reports health as the ratio of running instances to configured instances. For example, if you configured 10 instances but only 8 are running, the health score is 80%. The health manager tries to maintain all apps at 100%.

You can monitor the health of your app using apc app health <app-name>. To see why the app is not at 100%, you can do apc app logtail to see when instances fail and whether the health manager reports that the job is flapping.

Application Restart Modes

You can configure an application (or Docker job) to be automatically restarted by Apcera if the application fails (exits with a non-zero exit code) or finishes. A job is considered to be in a finished state if all its instances finished properly. If an instance is in a flapping state (has failed three times within five minutes) Apcera will wait for the job to come out of the flapping state before attempting a restart.

To specify an application or Docker job's restart mode, add the --restart option to the apc create app and apc docker run commands. This option accepts the following values:

  • always – Always restart the application, regardless of whether it failed or finished. This is the default behavior for application instances.
  • failure – Only restart on application failure (process exits with a non-zero exit code).
  • no – Never restart the application. This is the default behavior for Docker instances.

See Deploying an App for more information about these and other options when creating an application.

Tips for deploying specific app types

Apcera automatically detects many types of apps and uses the appropriate staging pipeline for them. Here are additional tips for some app types.

Ruby tips

The Gemfile is the key file that stagers for Ruby apps rely on. Because multiple Ruby versions can be available to apps in your cluster, be sure to specify a Ruby version in the Gemfile. For example,

```source '' ruby '2.1.2'

If a Ruby app uses Nokogiri, you can tell it to use the local copy of `libxml2` by adding this to the Gemfile:

# ensure nokogiri doesn't try to compile libxml2 itself

The system images that power Apcera's Ruby runtimes already include a recent version of libxml2, so Nokogiri doesn't need to build it.

Java tips

The easiest way to deploy a Java app is to use a WAR file, but you can use other means as well.

Follow these steps to deploy via a WAR file:

  1. Create a WAR file in the app's target directory — you can use Maven or Ant, or export directly from Eclipse. The only requirement is that the WAR file be a standard Java webapp and adhere to standard structure and conventions.

    See the Ant and Maven tutorials for reference.

  2. Deploy the application:

    $ apc app create war-test --start-cmd <your-start-command> --start

Deployments are limited to a single WAR file, which is automatically deployed with Tomcat.

Follow these steps to deploy using a Maven pom.xml file:

  1. Create a Java webapp with a Maven pom.xml file.

    To see an example, clone the example-java-jetty app from the Apcera sample-apps repo on Github.

  2. Deploy the application:

    $ apc app create no-war-test --start-cmd <your-start-command> --start

    Apcera uses the name of the main class to populate the start command, if it is not explicitly specified via your APC command.

Apcera supports the $JAVA_OPTS environment variable. For more information see Java.

Go tips

It is recommended that you set up your golang environment. If the application is deployed without a working golang environment, the app will be named app, as we are not able to detect the actual compiled application name.

Sample applications


The following tutorials demonstrate deploying various types of applications.