Creating a Web App and Connecting it to a Service

Use the Apcera platform to ingest Node source code to build a web front end application and connect the application to a Postgres or MySQL database for persistence.

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.

  • Downloaded the Apcera sample applications from GitHub and extracted it to sample-apps-master, or cloned the repository using Git.

  • Platform is bootstrapped with Postgres, MySQL, and NFS providers. These are installed by default with the Apcera Platform. To verify these providers are available, open a terminal and run the following command:

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

Deploy the demo-node-todo sample application

  1. From a terminal, change to the sample-apps/demo-node-todo directory.

    cd sample-apps-master/demo-node-todo/
    
  2. Deploy the demo-node-todo app with a custom route URL, replacing your-cluster with the name of your cluster and apcera-platform.io with your domain, if you used your own domain when installing.

    apc app create my-todos --start --routes http://todo.your-cluster.apcera-platform.io
    

    APC prompts you to provide values for the number of instances and amount of memory to allocate to each instance. Press enter to select the default values for each option.

    Deploy path [/sample-apps-master/demo-node-todo]: <enter>
    Instances [1]: <enter>
    Memory [256MB]: <enter>
    ...
    Is this correct? [Y/n]: <enter>
    ...
    Waiting for the application to start...
    [stdout] listening on port  4000
    App should be accessible at "http://todos.tutorial.apcera-platform.io"
    

    Apcera uses the NodeJS staging pipeline (stagpipe::/apcera::nodejs) to compile the application package and deploy it.

  3. When complete, open the application’s URL route in a web browser.

    As the application indicates in yellow, no databases are available to the application, so any todo items you enter won’t be persisted.

    Tutorial Image

Next, you’ll create a Postgres service and bind it to the application so items can be persisted.

Create a Postgres service and bind it to the application

Next, you’ll create a Postgres service using the postgres-provider installed with the Apcera platform. You’ll then bind the service it to the application.

  1. Open a terminal and run the following APC command to create a Postgres service named todos-db-postgres using the built-in Postgres provider (/apcera/providers::postgres-provider):

    apc service create todos-db-postgres --provider /apcera/providers::postgres-provider
    
  2. Bind the todos-db-postgres service to the my-todos application:

    apc service bind todos-db-postgres --job my-todos
    

    Press enter when prompted if you want to stop the job, apply the binding and restart the job.

  3. Reload the my-todos application in the browser.

    Enter some tasks and refresh the page in the browser to see that they are being persisted by the Postgres database.

    Tutorial Image

    Note that if you select the MySQL database option in the application you’ll see an error message because you haven’t connected a MySQL service to the application. You’ll do this next.

Create a MySQL service and bind it to the application

The steps to create and bind a MySQL service to the application mirror those you followed for the Postgres service. The only difference is that you create the service using the mysql-provider instead of the postgres-provider.

  1. Open a terminal and run the following APC command to create a MySQL service named todos-db-mysql using the built-in MySQL provider (/apcera/providers::mysql-provider):

    apc service create todos-db-mysql --provider /apcera/providers::mysql-provider
    
  2. Bind the todos-db-mysql service to the my-todos application:

    apc service bind todos-db-mysql --job my-todos
    

    Press enter when prompted to stop the job, apply the binding and restart the job.

  3. Reload the todos application in the browser and select the MySQL database option. Enter some tasks and reload the page to see that they are being persisted to the MySQL database.

    Tutorial Image

Analysis: Services and Bindings

This tutorial demonstrates how Apcera uses bindings to decouple an app from the services is requires.

The demo-node-todo sample app (in /app.js) references process.env.MYSQL_URI (in /lib/routes_ms.js) and process.env.POSTGRES_URI in (/lib/routes_pg.js). These values are provided to the app by Apcera as environment variables MYSQL_URI and POSTGRES_URI, repsectively, which are accessible with the env command when accessing the app via SSH (using the apc app connect command).

When you create each DB service and binding, the system creates a distinct instance of the database for the app. The connection credentials in the *_URI environment variable are ephemeral and can only be used by this todo app. You could also connect to the app database using the actual connection string specified in the provider connection. Or, you could write a rule against the semantic pipeline to allow only the emphemeral connections to the DB.