Creating Apps from Docker Images

This tutorial demonstrates how to deploy applications on Apcera from Docker images. You’ll first create and start a NATS server from the official NATS Docker image. You’ll then deploy a simple NATS client application from another Docker image and link it to the NATS server application. You will use a multi-job manifest to deploy the client application.

Requirements

To complete this tutorial your development environment have the following:

  • 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>.apcera-platform.io or apc target http://<your-cluster>.apcera-platform.io (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.

1: Create the NATS app from the public Docker image

First create an app from the official NATS Docker image.

  1. Select Launch > Docker Image.

    Tutorial Image

  2. Select the NATS image from the list of Docker images.

    Tutorial Image

  3. In the App from Docker Image form, enter nats-server for the application name and pick a namespace (default is fine) and click Submit.

    Tutorial Image

    A dialog shows the progress of downloading the Docker image layers and creating the job.

    Tutorial Image

  4. Once the application is created, the web console presents the app’s details view. Click the Logs tab to view the app’s log items that indicate the NATS server is running and listening for client connections on port 4222.

    Tutorial Image

Next you’ll create a simple NATS client from another public Docker image and create a job link to the nats-server application. The client regularly sends messages to the server, which displays the received message in its logs.

To create the NATS client app, you’ll use a multi-job manifest that references apcera/nats-ping-client Docker image. Multi-job manifests let you declaratively create and configure multiple applications in a JSON file.

  1. Download nats-client-manifest.json.zip and unzip the file to your desktop. The ZIP file contains the JSON manifest nats-client-manifest.json. The JSON file has the following contents:

    {
      "jobs": {
        "job::/sandbox/admin::nats-client": {
          "docker": {
            "image": "https://registry-1.docker.io/apcera/nats-ping-client:latest"
          },
          "state": "started",
          "links": {
            "nats": {
              "fqn": "job::/sandbox/admin::nats-server",
              "port": 4222
            }
          }
        }
      }
    }
    

    The manifest declares a job named nats-client that’s created from the specified Docker image (apcera/nats-ping-client:latest). The links field declares a job link between the client app and the nats-server app you created previously.

  2. If your user’s namespace is not /sandbox/admin change each instance of /sandbox/admin in the JSON file to /sandbox/<username> replacing <username> with your username. Save your changes to the file.

  3. Select Launch > Manifest in the left navigation.

    Tutorial Image

  4. Drag and drop the JSON file on the form, or click Browse to locate it.

    Tutorial Image

  5. Click Upload to upload the manifest to create the client application and link it to the NATS server app. Click Close when complete.

    Tutorial Image

  6. To confirm that the client is receiving NATS messages from the server, select the Logs tab on nats-client app’s details view. You should see a message once every second.

    Tutorial Image

Going Further: Create both apps in a manifest

In the previous step you used a multi-job manifest to create the NATS client app and link it to the NATS server. The following manifest (client-server-manifest.json.zip) creates and starts both the NATS server and client application from their respective Docker images, and creates a job link between the two applications.

You can deploy the manifest using the Web Console’s Launch > Manifest button as shown previously, or on the command-line using APC:

apc manifest deploy client-server-manifest.json
{
  "jobs": {
    "job::/sandbox/admin::nats-client-2": {
      "docker": {
        "image": "https://registry-1.docker.io/apcera/nats-ping-client:latest"
      },
      "links": {
        "nats": {
          "fqn": "job::/sandbox/admin::nats-server-2",
          "port": 4222
        }
      },
      "state": "started"
    },
    "job::/sandbox/admin::nats-server-2": {
     "docker": {
        "image": "https://registry-1.docker.io/library/nats:latest"
      },
      "state": "started"
    }
  }
}

See Using Multi-job Manifests for more information about multi-job manifests.