Debug a Live App Using Console App

This tutorial demonstrates how to perform live debugging of a deployed app using an app console session. A app console is a cloned instance of your app that runs within an Apcera capsule.

Overview

One way to troubleshoot a running app is to access it using SSH. Apcera lets you to expose SSH port 222 on an app and connect directly to the live instance (apc app connect <app-name>). From there you can explore the file system and attempt to debug the app. However, since the app is running this approach is not a good practice because you may disrupt the app. Furthermore, exposing SSH is not recommended for production apps.

To debug a production app without having to expose the SSH port and connect directly to the live instance, Apcera provides the app console feature. Using a console is the recommended approach for debugging a live app because it allows you to connect to a cloned instance of your app without exposing the SSH port on the live app. The app console session includes all service bindings present in the original app, and lets you debug the app without disturbing the running instance. This feature gives you a convenient way to debug live apps without the risk of exposing the SSH port and disrupting the running instance.

Prerequisite

  • Walkthrough – You will need to have deployed the demo-node-todo app as described in the walkthrough.

Instructions

Complete the steps that follow.

1. Verify that your my-node-todo-app is running.

apc app list

Or, alternatively:

apc app show my-node-todo-app

2. Enable SSH access to the app.

apc app update my-node-todo-app --allow-ssh --restart

This command updates the app and restarts it. On restart you should see that SSH port 222 is exposed.

3. Verify SSH access to the app.

apc app show <app-name>

For the Exposed Ports entry, you will see that SSH port 222 is listed. In addition, for the Tags entry you will see "ssh: true".

apc app connect <app-name>

You should be able to connect to the app via SSH and navigate the file system.

4. Remove SSH access.

apc app update my-node-todo-app —remove-ssh

Since allowing SSH access is not recommended for production apps, we remove SSH egress using the above command.

apc app show my-node-todo-app

You should see that the SSH port 222 is no longer exposed.

5. Create a console for the app and connect to the console.

apc app console my-node-todo-app

You will see a series of outputs indicating you have created a capsule for the app and connected to it. Notice that the connection to the capsule is via SSH but the live app has not exposed this port (you removed it). SSH is exposed for the cloned capsule app only so that you can debug it.

6. Debug the app using the console.

By using the app console command to clone the app, you can explore the app file system without disrupting the running instance:

  • Change directory to root: cd /
  • List the root directories: ls
  • Change directory to app: cd /app
  • List the app directories: ls
  • Issue the following command to read the contents of the app.js file: cat app.js
  • Issue the following command to read the contents of the package.json file: cat package.json

7. Stop and delete the app capsule.

exit

This command both stops and deletes the app console. If you run command apc app show my-node-todo-app you will see that there are no remnants of the console session. The original app instance is still running and the SSH port remains closed.