Apcera Walkthrough

This walkthrough shows how to use the Apcera Platform, including authoring policy, deploying apps, and consuming services. The walkthrough takes approximately 30 minutes to complete. At the end you will have a fully-functioning web app running in the Apcera Platform.

If you are using the Apcera Platform Community Edition version 2.0 or later, check out the Apcera Developer Portal for the latest version of this getting started tutorial and many more in both written and video format.

Steps

Prerequisites

Before starting the walkthrough, check that you have completed the following prerequisites:

  • Deployed the Apcera Platform Community Edition if you are using the trial edition, or
  • Installed APC for your platform if your are using a managed or production platform, and
  • Targeted your platform and logged in.
  • Have either a MySQL or Postgres provider registered on your cluster. Both these providers are installed with Apcera Platform Community Edition 2.0 and later. To verify if your targeted cluster has these providers run apc provider list -ns / in a terminal, or use the Providers view in the web console. The following command output is typical for a Community Edition installation:

      apc provider list -ns /
      Working in "/"
      ╭───────────────────┬──────────┬───────────────────┬─────────────╮
      │ Name              │ Type     │ Namespace         │ Description │
      ├───────────────────┼──────────┼───────────────────┼─────────────┤
      │ apcfs             │ nfs      │ /apcera/providers │ NFSv4       │
      │ mysql-provider    │ mysql    │ /apcera/providers │             │
      │ postgres-provider │ postgres │ /apcera/providers │             │
      ╰───────────────────┴──────────┴───────────────────┴─────────────╯
    

    If you don't have a provider registered of type mysql or postgres then you will need to create at least of one those providers yourself. A common way to do this is using the Postgres and MySQL packages provided by Apcera. See Creating a Postgres service from an Apcera Package and Creating a MySQL service from an Apcera Package.

Download Apcera sample apps

Clone the sample apps from the Apcera repository on GitHub.

git clone https://github.com/apcera/sample-apps.git

Alternatively, you can download the sample apps as a ZIP file and extract it to a known local directory.

Author policy to deploy jobs

Everything you do in Apcera is controlled by policy. Here you learn how to author policy that lets you create jobs.

It is likely that your platform has policy in place that lets you do things like create jobs, services, etc. This will be the case if you are using the Apcera Platform Community Edition. Nonetheless, you can use this section as a primer on policy authoring.

Author policy that permits you to deploy jobs in your namespace:

  1. Log in to the Apcera web console for your platform.

    See logging in to the web console.

  2. Click Policy in the left navigation menu.
  3. Click Create.

    NOTE: You need policy permissions to create and edit policy documents. If you don't have policy permissions, check with your administrator.

  4. In the policy name field, enter a descriptive name (for example, user-policy-walkthrough). Policy document names may only contain letters, numbers, _, and -.
  5. In the policy editor field, enter the following policy rule.

     job::/sandbox/user
     {
         if (auth_server@apcera.me->name=="user")
         {
             permit create, read, update, delete
             permit map
         }
     }
    
    • Replace both occurrences of user with your actual user name.
    • Get your namespace with the apc namespace command, and your user name using apc login show.
  6. Click Create Document when you are done. The Policy Editor validates the policy syntax for you.

This policy grants you permissions to deploy and manage jobs in your namespace. The policy identifies you by your username which is assigned to you by the Auth Server when you logged in to the system and were granted an access token to the platform.

Author policy that permits you to deploy packages in your namespace:

  1. Open the policy document you just created in the web console.
  2. Click Edit Policy.
  3. Add the following rule, replacing both occurrences of user with the your actual username:

     package::/sandbox/user
     {
         if (auth_server@apcera.me->name=="user")
         {
             permit create, read, update, delete
             permit use
         }
     }
    
  4. Click Apply Changes when you are done.

This policy grants you permission to deploy packages in your namespace. Deploying apps requires permissions on both the job and package realms.

Here is a screenshot of the two policies you have written thus far:

screenshot

Deploy web app

In this section you deploy a web app using Apcera. Apcera can deploy a diverse set of workloads, including:

Apcera encapsulates each of these workloads in an abstraction called a job, addressing but hiding the idiosyncrasies of each, so Apcera can apply the same orchestration and governance patterns to all of them.

The demo-node-todo app is a Node.js application with a web frontend that can write to Postgres or MySQL databases. After you deploy this app, you will connect it to backend databases in the next section.

1. Deploy the demo-node-todo app.

Using the APC client command-line interface, change directory to the app home directory:

cd sample-apps/demo-node-todo

Deploy and start the web app using the apc app create <app-name> command:

apc app create demo-node-todo --start

You can define deployment options on the command line each time you deploy, such as the <app-name> and --start, or you can use an app manifest. Options entered on the command line override those in the manifest.

Configure the deployment by pressing Enter (Y) to accept the default value for each of the following deployment settings:

apc app create demo-node-todo --start
Deploy path [~/sample-apps/demo-node-todo]: <enter>
Instances [1]: <enter>
Memory [256MB]: <enter>
╭────────────────────────────────────────────────────────────╮
│                     Application Settings                   │
├───────────────────┬────────────────────────────────────────┤
│              FQN: │ job::/sandbox/admin::demo-node-todo    │
│        Directory: │ /dev/sample-apps/demo-node-todo        │
│        Instances: │ 1                                      │
│          Restart: │ always                                 │
│ Staging Pipeline: │ (will be auto-detected)                │
│              CPU: │ 0ms/s (uncapped)                       │
│           Memory: │ 256MiB                                 │
│             Disk: │ 1GiB                                   │
│           NetMin: │ 5Mbps                                  │
│           Netmax: │ 0Mbps (uncapped)                       │
│         Route(s): │ auto                                   │
│  Startup Timeout: │ 30 (seconds)                           │
│     Stop Timeout: │ 5 (seconds)                            │
╰───────────────────┴────────────────────────────────────────╯

Is this correct? [Y/n]:

APC presents you with a summary of your application's settings. Press Enter ("Y") at the prompt to deploy the app.

Apcera uploads your code, stages it, that is, prepares it for launch. Staging is the process by which Apcera detects the source code, identifies and downloads dependencies, updates configuration files, sets environment variables, specifies the start command, and complies the code into a runnable package. In this case, Apcera reads the package.json file and uses the stagpipe::/apcera::nodejs staging pipeline to deploy the app.
You should see the following output indicating that your app is successfully deployed:

Is this correct? [Y/n]:
Packaging... done
Creating package "demo-node-todo"... done
Uploading package contents... done!
[staging] Subscribing to the staging process...
[staging] Beginning staging with 'stagpipe::/apcera::nodejs' pipeline, 1 stager(s) defined.
[staging] Launching instance of stager 'nodejs'...
[staging] Downloading package for processing...
[staging] Stager needs relaunching
[staging] Launching instance of stager 'nodejs'...
[staging] Downloading package for processing...
[staging] Executing "npm install --production"
[staging] mysql@2.9.0 node_modules/mysql
[staging] ├── bignumber.js@2.0.7
[staging] └── readable-stream@1.1.13 (string_decoder@0.10.31, isarray@0.0.1, inherits@2.0.1, core-util-is@1.0.2)
[staging] Staging is complete.
Creating app "demo-node-todo"... done
Start Command: node ./app.js
Waiting for the application to start...
[stdout] listening on port  4000
App should be accessible at "http://demo-node-todo-155qp9.sf.apcera-platform.io"

The apc app create command pushes your app to Apcera. This creates a URL that is the route to your app. The default route URL is composed of your application name, followed by six random alphanumeric character, followed by the cluster and domain (demo-node-todo-155qp9.sf.apcera-platform.io, in this case).

An app deployed to Apcera can listen on a port of its choice. In this example, demo-node-todo is listening on port 4000 and is deployed to the /sandbox/admin namespace. Namespaces organize entities in Apcera, much as folders do in file systems. Apcera uses hierarchical namespaces to indicate critical functional areas. Every customer-facing entity in Apcera (such as this sample app) has one parent namespace. The default namespace for an Apcera user is /sandbox/<username>.

2. Verify app deployment.

Using a web browser, visit your app's generated route URL to see the app you just deployed.

When you enter data, you see a warning that there are no databases attached to the app; you attach a database later in the walkthrough.

screenshot

Manage your app

In this section you manage your deployed app using the web console and APC.

1. Manage the app using the web console.

Log in to the web console for your platform.

Explore the interface and select your app so that the Job Details view appears. Verify that 1 instance of the app is running. You will also see resource utilization statistics that are graphed for this instance. Note that viewing platform information requires policy permissions.

2. Get app details using APC.

Using the APC client, run the following command:

apc app list

You should see that you app is listed and deployed in your namespace. Since an app is a job, you can also use apc job list to view the job.

Run the following command to view app details:

apc app show demo-node-todo

This command displays additional details about your app, including its fully qualified namespace (FQN), state, instances, resources, process(es), ports, routes, tags, packages, and environment variables.

3. Get job health using APC.

Run the following command to view the app's health:

apc app health demo-node-todo

This command checks the health of your app. You should see that the app's Status is Running, it's Health Score is 100%, and the ratio of Running Instances to the number of expected instances is 1/1.

apc app health demo-node-todo
Looking up "demo-node-todo"... done
Retrieving job health... done
╭────────────────────┬─────────────────────────────────────╮
│ Job:               │ job::/sandbox/admin::demo-node-todo │
├────────────────────┼─────────────────────────────────────┤
│ Status:            │ Running                             │
│ Health Score:      │ 100%                                │
│ Running Instances: │ 1/1                                 │
╰────────────────────┴─────────────────────────────────────╯

Author policy for services

In this section of the walkthrough you author policy to create services in your namespace and bind jobs (apps) to those services.

1. Author policy to permit service creation.

  • Log in to the Apcera web console for your platform.

  • Select the Policy icon.

  • Select your policy that you created previously.

  • In the Policy Editor field, add the following rules to the policy, substituting user with the actual value for both occurrences.

  • Click Apply when you are done. The Policy Editor validates the policy syntax for you.

service::/sandbox/user
{
  if (auth_server@apcera.me->name=="user")
  {
    permit create, read, update, delete
    permit bind
  }
}

This policy lets you create, read, update, and delete services in your namespace (/sandbox/user). It also permits binding. At this point you could proceed with creating one or more services in your namespace. However, your app would not be able to consume such services because you have not authorized binding on the job.

2. Author policy to permit job binding.

  • In the web console, select your policy document.

  • In the Policy Editor field, update the policy you created previously for the job realm with the bind permission.

  • Click Apply when you are done. The Policy Editor validates the policy syntax for you.

job::/sandbox/user
{
  if (auth_server@apcera.me->name=="user")
  {
    permit create, read, update, delete
    permit map, bind
  }
}

These policy rules permit you to bind jobs to services in your namespace (/sandbox/user). Policy on service binding is a two-way handshake. You must have two rules: one that permits service binding, and another that permits job binding.

3. Export policy file (optional).

Here is the complete set of policies you have authored in this walkthrough. Each realm declaration indicates a new policy. The policies are stored in a policy document file. You can export the policy file using the apc policy export command. The policy document(s) will be exported to the working directory as *.pol files.

job::/sandbox/user
{
    if (auth_server@apcera.me->name=="user")
    {
        permit create, read, update, delete
        permit map, bind
    }
}

package::/sandbox/user
{
    if (auth_server@apcera.me->name=="user")
    {
        permit create, read, update, delete
        permit use
    }
}

service::/sandbox/user
{
  if (auth_server@apcera.me->name=="user")
    {
        permit create, read, update, delete
        permit bind
    }
}

Create services and bindings

You can bind applications to services without code changes to your app. A service is any backend that provides data over an API, such as databases, messaging, and key-value stores. A service provider provisions service instances. Whatever is provisioned for you, is referred to as a service. A service gateway configures service bindings to connect apps to services, and manages services, service providers, and service bindings. Apcera includes several built-in service gateways, including ones for MySQL, Postgres, and Redis.

In this part of the walkthrough you create a PostgreSQL service and bind your web app to it. You then create a MySQL service and bind your web app to it. The creation and binding of each service is the same, the only difference being the provider. This demonstrates how Apcera is consistent with service creation and binding across the platform.

To complete this portion of the walkthrough, you need to have at least one Postgres or MySQL provider registered with the platform]. See Prerequisites for details.

1. Use APC or web console to verify the available providers.

Run apc providers list -ns / to view all providers registered on your target cluster (or click Providers in the web console).

You should see that the MySQL and PostgreSQL providers are available in the /apcera/providers namespace, as shown below. Apcera clusters include built in service gateways for both of these service providers.

apc provider list -ns /
Working in "/"
╭───────────────────┬──────────┬───────────────────┬─────────────╮
│ Name              │ Type     │ Namespace         │ Description │
├───────────────────┼──────────┼───────────────────┼─────────────┤
│ apcfs             │ nfs      │ /apcera/providers │ NFSv4       │
│ mysql-provider    │ mysql    │ /apcera/providers │             │
│ postgres-provider │ postgres │ /apcera/providers │             │
╰───────────────────┴──────────┴───────────────────┴─────────────╯

2. Create a service for the PostgreSQL provider and bind your app to the service.

Using the built-in Postgres provider, create a Postgres Service and bind your app to this service using the following apc service create command. Verify the settings output by APC and press Enter (Y) to create the service and binding.

apc service create my-postgres-service --provider /apcera/providers::postgres-provider --job demo-node-todo
╭────────────────────────────────────────────────────────────────╮
│                   Service Creation Settings                    │
├─────────────────┬──────────────────────────────────────────────┤
│        Service: │ service::/sandbox/admin::my-postgres-service │
│       Provider: │ /apcera/providers::postgres-provider         │
│ Job to bind to: │ demo-node-todo                               │
│        Binding: │ (will be auto-generated)                     │
╰─────────────────┴──────────────────────────────────────────────╯

Is this correct? [Y/n]:
Creating service... done
Binding service "my-postgres-service" to "demo-node-todo"...
Job must be stopped to bind to service. Do you want to stop it, apply the binding, and start it again?
Restart and proceed? [Y/n]:
Stopping job... done
Creating binding... done
Starting job... done
Waiting for the job to start...
All instances started!
Success!

You should see that the service is created, the job (your app) is stopped (you will be prompted to stop it if it is running), the binding is created, and the job is restarted.

You do not have to create the job binding when you create the service. You can create a service standalone and then bind a job to it at a later time. We do them together for convenience. But, keep in mind that to consume a service you must bind your app to it.

The demo-node-todo app now persists data to the Postgres DB between page refreshes. Its binding includes the connection information and credentials that allow it to reach specific service instances.

screenshot

  • Select the "Postgres" option in the web interface.
  • Enter some text in the “What needs to be done?” field.
  • Press Enter.

The data you entered should be accepted without error. This means that your app is successfully connecting to the PostgreSQL DB. By contrast, if you select the "MySQL" option, you receive an “Error connecting to MySQL” because your app is not yet connected to the MySQL DB. You create that service and binding next.

To clear the data you entered in the web page, click the "Complete All Tasks" button. You can also show the SQL and execute SQL commands against the DB.

3. Verify the service, job binding, and environment variables.

Run the following command:

apc service list

You should see that the 'my-postgres-service' you created and is listed and that the provider type is postgres. The type maps to the service gateway used by the service.

apc service list
Working in "/sandbox/admin"
╭──────────────────────┬──────────┬────────────────┬────────────────────────────────────────────────┬────────────╮
│ Name                 │ Type     │ Namespace      │ Provider                                       │ Description│
├──────────────────────┼──────────┼────────────────┼────────────────────────────────────────────────┼────────────┤
│ my-postgres-service  │ postgres │ /sandbox/admin │ provider::/apcera/providers::postgres-provider │            │
╰──────────────────────┴──────────┴────────────────┴────────────────────────────────────────────────┴────────────╯

Run the following command:

apc job list

You should see both the app and the semantic pipeline instance created for the service.

apc job list
Working in "/sandbox/admin"
╭──────────────────────────────────┬──────┬────────────────┬──────────┬───────────╮
│ Name                             │ Type │ Namespace      │ Status   │ Instances │
├──────────────────────────────────┼──────┼────────────────┼──────────┼───────────┤
│ demo-node-todo                   │ app  │ /sandbox/admin │ started  │ 2/2       │
│ demo-node-todo/postgres/6a729575 │ job  │ /sandbox/admin │ started  │ 2/2       │
╰──────────────────────────────────┴──────┴────────────────┴──────────┴───────────╯

Run the following command:

apc app show demo-node-todo

The "Bound Services" section lists of the command output lists the FQN of the service and the service provider, and environment variables the job can use to connect to the service.

apc app show demo-node-todo
╭──────────────────────┬────────────────────────────────────────────────────────────╮
│ Job:                 │ demo-node-todo                                             │
├──────────────────────┼────────────────────────────────────────────────────────────┤
│ FQN:                 │ job::/sandbox/admin::demo-node-todo                        │    
│ ...                  │ ...                                                        |  
| Bound Services       │                                                            |
|                      │                                                            |
| 1. Service:          │ service::/sandbox/admin::my-postgres-service               |
|    Provider:         │ provider::/apcera/providers::postgres-provider             |
|    Environment:      │ JDBC_POSTGRES_URI                                          |
|                      │ MYPOSTGRESSERVICE_URI                                      |
|                      │ POSTGRES_URI                                               |

4. Create a service for the MySQL DB provider and bind your app to it.

Repeat the above process, this time using the MySQL provider as the basis for the service and biding.

apc service create my-mysql-service --provider /apcera/providers::mysql-provider --job demo-node-todo

5. Verify that the app can connect to the MySQL service.

Verify that your app can connect to the MySQL DB:

  • Select the "MySQL" option in the web page.
  • Enter some text in the “What needs to be done?” field.
  • Press Enter.

The data you entered should be accepted without error. This means that your app is successfully connecting to the MySQL DB.

Click the "Postgres" button. You should not receive an error, indicating that your app is successfully connecting to both DB providers using the service definitions you created.

Manage and scale your app

Running additional instances of an app can allow the app to handle increases in user loads and concurrent requests. For many apps, increasing the available disk space or memory can improve overall performance. These adjustments are called scaling the application.

Scaling an app vertically changes the limits on disk space or memory that apply to all instances. Scaling an app horizontally means adding or reducing the number of instances. Incoming requests to an app are automatically load balanced across all instances of the app.

To scale your app using the web console:

  1. On the Summary tab of the app's details view, In the job details pane, change Expected Instances count from 1 to 2.

    screenshot

  2. Press enter or click the check mark to confirm your change.

To perform the same action on the command line, you call apc app update and specify the number of expected instances with the --instances <count> parameter, for example:

apc app update demo-node-todo --instances 2

Scaling can be limited by policy. For example, if you were to request 1000 instances, Apcera informs you that you have violated the following policies:

Namespace memory quota of 2GB on "quota::/sandbox/user" exceeded

Which is established by the following policy:

quota::/sandbox/user {
  { total.package.size 500MB }
  { total.memory 2GB }
  { total.disk 10GB }
  { total.network 1Gbps }
}

Policy lets you place fine-grained limits on the extent to which an app can be scaled.

Tail job logs

To tail your application's log output, click the Logs tab on the job's details view. This displays any output from your app sent to the standard error or standard out streams, and system and system error event messages.

You can also tail job logs using APC, for example: apc job logs demo-node-todo.

screenshot

Going further

In this walkthrough you learned how to use the Apcera Platform, including authoring policy, deploying apps, and consuming services. Now that you have finished the walkthrough, check out our libarary of tutorials to get more hands-on experience with the platform. See also our video library of product demonstrations and tutorials.