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
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 "http://website-s7aks8.apceraaws.apcera-platform.io" Success!
To view the running site, open the link displayed on successful app deployment (
http://website-s7aks8.apceraaws.apcera-platform.io"). 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.
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.
apc help app create produces a list of this command's options. Here are a few of the more important ones:
||Path to the app (default: current path)|
||Staging Pipeline to use (default: auto-detected)|
||Encrypt the volume the container data is mounted on. See Encrypting application data volumes.|
||Allow the app open outbound network access|
||Sets an environment variables on the app. Multiple values can be supplied by invoking multiple times (e.g.
||String that specifies the command to start the application. See Application start command for details.|
||Start the app after deploying it|
||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.|
--stagingdeals 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-egresstells Apcera that it's OK for the deployed app to access arbitrary IP addresses (for example, public websites).
--env-setsets environment variables on the deployed app.
pkg-envsets 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
--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/parseDb.sh && ./start_app.sh'
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.
apc app logsretrieves 20 log lines. You can fetch up to 1,500 lines using the
$ 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:
||Allows open outbound network access on the app||Yes|
||Milliseconds of CPU time per second of physical time (default: Uncapped)||Yes|
||Amount of disk space to allocate, in MB (default: 1GiB)||Yes|
||Sets environment variables on the app||Yes|
||Unsets environment variables on the app||Yes|
||Specifies the GID to run the process as.||Yes|
||Updates the number of instances of the app (default: 0)||No|
||Amount of memory to allocate, in MB (default: 256MiB)||Yes|
||The app's local name.||No|
||Amount of maximum network throughput to allow (ceiling), in Mbps (default: 0Mbps, Uncapped)||Yes|
||Amount of network throughput to allocate (floor), in Mbps (default: 5Mbps)||Yes|
||Virtual network to join, leave, or enable/disable network multicast or broadcast on.||Yes|
||Adds the package specified by NAME to the app, installed at PATH (default: /)||Yes|
||Removes the package specified by NAME from the app||Yes|
||Exposes a port||No|
||Removes an exposed port||No|
||Modifies the start command of the app. See ||Yes|
||Number of seconds the system waits for an app to start before triggering a failure||Yes|
||Specifies the UID to run the process as.||Yes|
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.
# Ignore all logfiles and tempfiles. /log/*.log /tmp # Ignore Java .class files *.class # Ignore compiled Object files, Static and Dynamic libs (Shared Objects) *.o *.a *.so
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
config.ru 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.
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
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,
$ 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 root@ip-10-0-1-21:/#
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
0 inside the container).
App instances, on the other hand, run code as Linux container user
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.
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.
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 'https://rubygems.org' 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: ```ruby # ensure nokogiri doesn't try to compile libxml2 itself ENV["NOKOGIRI_USE_SYSTEM_LIBRARIES"] = "true"
The system images that power Apcera's Ruby runtimes already include a recent version of
libxml2, so Nokogiri doesn't need to build it.
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
WARfile in the app's target directory — you can use Maven or Ant, or export directly from Eclipse. The only requirement is that the
WARfile be a standard Java webapp and adhere to standard structure and conventions.
Deploy the application:
$ apc app create war-test --start-cmd <your-start-command> --start
Deployments are limited to a single
WARfile, which is automatically deployed with Tomcat.
Follow these steps to deploy using a Maven
Create a Java webapp with a Maven
To see an example, clone the
example-java-jettyapp from the Apcera sample-apps repo on Github.
Deploy the application:
$ apc app create no-war-test --start-cmd <your-start-command> --start
Apcera uses the name of the
mainclass 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.
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.
The following tutorials demonstrate deploying various types of applications.