This is documentation for Apprenda 7 and 8.
Documentation for older versions are also available.

Linux Services

Linux Services is the Apprenda feature name for the ability to natively run generic Linux executables on Apprenda. A Linux Service can be any application that is launched through an executable file (e.g. shell scripts, C-compiled native code, Ruby, python, etc.).

If an Apprenda Platform installation includes Linux Servers, it supports native deployment, monitoring, and scaling of Linux Services without additional setup by your Platform Operator.

Configuring a Linux Service to run on Apprenda

Apprenda Archive 

In order to be deployed on the Apprenda Platform, a Linux Service must be packaged as an Apprenda Archive. The archive format requires a linuxServices folder which contains a named artifact-specific sub-folder wherein workload artifacts may be placed. Unless the archive will be used for a Docker Workload (and contains a Dockerfile), it should include "start"and "stop" scripts; the application may also provide its own binaries.

Below is the structure for an Apprenda Archive, SimpleService.zip containing the linuxServices and a Deployment Manifest:

The linuxServices folder contains a subdirectory for the Linux Service SimpleService, which houses application binaries and the requisite start and stop scripts:

Main process PID file/"start" script

In order for Apprenda to monitor the "main process" (a shell script could potentially start multiple collaborating processes) of the Linux Service, Apprenda provides an environment variable named $APPRENDA_WORKLOAD_PIDFILE pointing to the PID-file where it expects to find the PID of the main process launched by the start script (technically, Apprenda could have attempted to monitor ALL processes launched by the cgroup; however, doing so would cause unnecessary complications w/o bringing any tangible benefits). Thus, the "start" script must output the PID of this "main process" into the location this environment variable specifies.

Sample start.sh script

#!/bin/bash
COUNTER=40
echo "start.sh is running"
echo "Putting pid into $APPRENDA_WORKLOAD_PIDFILE"
echo $$ >"$APPRENDA_WORKLOAD_PIDFILE"
echo "----------------------- Environmental Variables -------------------"
printenv
echo "----------------------- End Environment Variables -----------------"
while true; do
 sleep 1
 echo "..zzz..";
done

If the start script fails to output a PID into the $APPRENDA_WORKLOAD_PIDFILE, the deployment of the Linux Service fails and a message is shown to the user indicating the same.

Deployment Manifest

The Application Archive for a Linux Service application must include a Deployment Manifest that references the named artifact-specific sub-folder:

Sample DeploymentManifest.xml for Linux Services

<?xml version="1.0" encoding="utf-8"?>
<appManifest xmlns="http://schemas.apprenda.com/DeploymentManifest"
             xmlns:xsi="http://www.w3.org/2001/XMLSchema-instance"
             xsi:schemaLocation="http://schemas.apprenda.com/DeploymentManifest http://apprenda.com/schemas/platform/7.0/DeploymentManifest.xsd" >

  <applicationServices level="None"/>
  <linuxServices>
      <service name="SimpleService">
        <environmentVariables>
          <variable name="test" value="Test Environment Variable" />
          <variable name="foo" value="$#APPLICATIONALIAS#$" />
        </environmentVariables>
        <commandLineArguments>
          <argument name="firstArg" />
          <argument name="secondArg" />
          <argument name="appAlias=$#APPLICATIONALIAS#$" />
        </commandLineArguments>
        <ports>
          <dynamicPort portName="HTTP" httpMapped="true" />
          <dynamicPort portName="OTHER" />
        </ports>
        <tokenReplacements>
          <tokenReplacement>
            <includePatterns>
              <include>**/*.strange</include>
            </includePatterns>
            <excludePatterns>
              <exclude>**/exclude*</exclude>
            </excludePatterns>
            <replacements>
              <replacement token="$#CUSTOMTOKEN#$" value="Replaced Token" />
            </replacements>
          </tokenReplacement>
        </tokenReplacements>	
      </service>
   </linuxServices>
  
</appManifest>

Token Replacement and Environment Variables

The list of Apprenda Tokens available for use by Linux Service components can be found here.

Your Platform Operator controls the default token replacement patterns for Linux Services (including the types of files for which token switching will be performed) through the the value set for the Hosting.Linux.TokenFilePatterns setting in the Platform Registry. As needed, developers may replace or supplement these defaults at the component level through an application's Deployment Manifest.

Environment Variables are also supported for Linux Services and may be configured through the Deployment Manifest.

Port allocation and HTTP routing

Ports can be specified for a Linux Service through the Deployment Manifest. Ports may be static or dynamic. Both static and dynamic ports may be declared httpMapped.

Static ports (included primarily to support legacy applications) are pre-set; specifying a static port in the Deployment Manifest will permit one instance of the application to listen on that port, and such applications cannot be scaled on a single Linux server as the port is allocated to the first instance deployed.

Dynamic ports permit a developer to merely specify that the workload requires a port, and the Platform allocates a port and makes it available to the workload (as environment variables and tokens to be token-switched). The naming convention is as follows: for a port named "FOO" in the manifest, the platform creates an environment variable "$PORT_FOO" and an Apprenda Token  "$#PORT_FOO#$".

# In the snippet below (if running docker as a plain linux service), the dynamic port named "PLAY_HTTP" is token switched into the start script
docker run  -v /apprenda/instances/$INSTANCEID:/apprenda/instances/$INSTANCEID -w="/apprenda/instances/$INSTANCEID" --name="$INSTANCEID" -e "envVar1=envVal1" -p $#PORT_PLAY_HTTP#$:9000  "apprenda_$INSTANCEID"

When a static or dynamic port is marked httpMapped="true", the Platform will use that port to route HTTP traffic to the Linux Service application using the URL type defined in the Dev Portal. For path-based URLs the workload must serve requests at the given path (e.g. /myapp-v1); for subdomain-based URLs the workload must serve requests at the root context (/).

Deploying and Managing Linux Services

Once your Linux Service has been configured and packaged to run on Apprenda, it can be uploaded, promoted, and deployed like any other Apprenda guest application as explained in the Deploying Your Applications section of our documentation. Some configuration and management options will be limited.

Linux Services functionality supported in the current version of Apprenda

​The following are available as part of the Linux Services functionality in the current version of the Apprenda Platform:

Limitations to Linux Services support

The following are not available for Linux Services for the current version of the Apprenda Platform:

  • Any User Access Model other than "Anyone" (this corresponds to the Application Services Level of "None" in the Deployment Manifest). Authentication, Authorization, and Multi-tenancy are not supported at this time.
  • Any Platform functionality that requires a User Access Model other than "Anyone" (such as Securables and Features).
  • Advanced logging controls 
  • Apprenda Guest Application API usage
  • Monitoring (resource utilization metrics and stats)
  • Anything that is backed by the distributed cache (including session replication)
  • Debugging (ability to SSH into processes)