Using Capsules to Quickly Create Custom Computing Environments

This tutorial demonstrates how to use capsules to create a custom computing environment that can be saved and re-used as the basis for other applications. In this case, you create a capsule from the Ubuntu 14.04 package provided by Apcera. You then connect to the capsule over SSH and perform a basic install of Apache web server using apt-get. You’ll then create a capsule “snapshot”, a package containing just the changes introduced to the capsule’s file system. This resulting package can be used to create other application or capsules.


  • Apcera Platform installed and running.
  • APC (command-line client) configured to target your cluster and you can log in:

    • To target your cluster run apc target https://<your-cluster> or apc target http://<your-cluster> (if your cluster doesn’t use SSL).
    • apc login --basic

      Tip: To get the target URL or web console URL for your cluster, run apcera-setup info.

Create a capsule running Ubuntu

  1. Open the web console for your cluster and select Launch > Capsule.

    Tutorial Image

  2. Click Ubuntu 14.04 in the Create New Capsule form.

    Tutorial Image

  3. Enter apache-capsule for the capsule name, select a namespace for the capsule (default is fine), and check the Allow Egress option.

    Tutorial Image

  4. Click Submit.

Connect to the capsule and install Apache

Next you’ll connect to the capsule over SSH using a terminal and install Apache.

  1. Run the following command to connect to the capsule, where’s you are are dropped into a Bash shell.

    apc capsule connect apache-capsule
  2. Run the following commands to update Ubuntu instance’s package sources and install Apache.

    apt-get update && apt-get install apache2

    Press enter (Y) when prompted to continue installation.

  3. Start Apache so you can test the installation.

    mkdir /var/lock && apachectl -DFOREGROUND

    You will see the following message, indicating Apache is running at the specified IP address: AH00558: apache2: Could not reliably determine the server's fully qualified domain name, using Set the 'ServerName' directive globally to suppress this message. You can ignore the ServerName portion of the message for this tutorial.

  4. Exit the SSH session.

    Enter Control + c then type:


Create a snapshot of the capsule

Next you’ll use the apc capsule snapshot command to create a package containing the changes introduced to the capsule’s file system by installing Apache. This package can then be used to create other applications, or as a dependency or requirement on other packages.

  • In a terminal enter the following command to create a package named apache-snapshot:

    apc capsule snapshot apache-capsule --name apache-snapshot

    When prompted, press enter to accept the snapshot settings.

    This process can take a couple of minutes. A message appears in the terminal indicates when the package was created successfully.

    Created "package::/sandbox/admin::apache-snapshot"

Create a new application from the package snapshot

At this point you have learned how easy it is to create a capsule and snapshot it to create a reusable package. To go further, you can create an app from the snapshot as described next.

Create a new application from the package (snapshot) you created previously. To do this you will use the apc app from package command.

  • In a terminal, run the following APC command to create the application and provide the necessary start command to start Apache:

    apc app from package apache-app --package apache-snapshot --disable-routes --start-cmd "sudo mkdir /var/lock && sudo apachectl -DFOREGROUND"


    • The --disable-routes option is used to disable default route generation and port assignment because you will manually add a port and route.
    • By default, the Apache process forks and runs in the background. To the cluster’s Health Manager this appears as if the application process has ended, and is flagged as being unhealthy. Therefore, the process must be run in the foreground.

Expose port 80 on the application and add a route

At this point the Apache process is running on the app but is unreachable because no ports have been exposed on the application. The last step is to expose port 80 and add a route to that port.

  1. Open your cluster’s Web Console.

    Tip: Use the apcera-setup info command to get your cluster’s console address.

  2. Select Apps from the left navigation and select apache-app from the list of apps.

    Make sure you are updating the apcahe-app job and not *apache-capsule**.

  3. On the app’s Networking tab, click Add Port on the job’s Networking tab.

  4. In the Add New Port form, enter 80 in the Number field and check the Include in Health Check option.

  5. Click Submit to expose the port.

    Tutorial Image

  6. To add a route, click Add Route on the app’s Networking tab.

  7. Enter the following in the Add a Route form:

    • Endpoint – Use the default route generated for you, or enter a custom route.
    • Weight – Leave the value at the default value of 0.
    • Port – Select 80 from the pop-up menu.

    Tutorial Image

  8. Click Submit to create the route.

  9. Click Start on the application’s details view and wait until the job has started (green check mark appears next to app name).

    Tutorial Image

  10. When the app has started, click the route link button to view the default Apache home page.

    Tutorial Image

    Tutorial Image