Installing and Using APC

APC is the Apcera command line tool you use to interact with the Apcera Platform.

You install APC on your local machine. Once you install APC you identify, or target, the platform you want to use. To target the platform you must know its domain name (my-cluster.apcera.com, for example).

You do not need to install it the APC client if you are using Apcera Platform Community Edition. The apcera-setup tool downloads APC to your local working directory.

Installing APC

Follow these steps to install APC.

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

2. Download the APC installer for your platform.

  • Click the Help icon in the lower left of the web console.

    screenshot

  • Download the apc.zip file for your platform:

    • Download for Mac

    • Download for Linux (64-bit)

    • Download for Windows (32-bit)

    • Download for Windows (64-bit)

3. Install the APC client by extracting and running the executable you downloaded.

  • Mac users: Double-click the apc.pkg package file and install APC.

  • Linux users: Extract the contents of the apc.zip file (apc) and run it.

  • Windows users: Extract the contents of the apc.zip file (apc.exe), copy it to a directory in your system's %PATH% environment variable, then run it.

4. Verify APC installation.

  • Open a terminal and type apc help.

  • Verify that you get a list of available APC commands.

5. Target your platform and log in.

APC installation directory

APC installs in the /usr/local/bin directory. You need to have read/write permissions on this directory to be able to use APC. If, after installing APC, you cannot perform an APC command such as apc help, check that you have proper permissions on this directory.

APC Settings File (.apc)

APC saves its current settings to a file called .apc that, by default, is located in your user's home directory ($HOME). To use a different directory, set the APC_HOME environment variable to desired directory where APC will save this file. This is useful, for example, if you want to maintain settings for different clusters you need to access. For example, you could use the default .apc file in the $HOME directory for one login, and set the APC_HOME variable to another location, such as export APC_HOME="$HOME/apc".

APC Environment Variables

APC reads from the following environment variables to modify it's behavior.

APC_HOME Path to directory in which to save the .apc settings file; default is $HOME.
APC_BATCH Set to disable interactive input globally.
HTTP_PROXY Proxy URL, if your networking environment requires a proxy for HTTP.
NO_PROXY Comma-separated list of domains that override HTTP_PROXY.

Targeting your platform and logging in using APC

Logging in to Apcera using APC requires credentials. Follow the steps below to login to your platform using APC.

The steps for logging in are different depending on if you using basic authentication or an identity provider such as Google auth. Once you are logged in to your platform, you can begin using APC to deploy apps to the platform.

APC target with basic auth login

If you are using basic authentication, target your platform and log in as follows:

1) Use command apc target to identify your platform to APC:

apc target http://sub-domain-name.apcera-platform.io
Targeted [http://sub-domain-name.apcera-platform.io]

Where sub-domain-name is the unique name for your platform.

NOTE: APC defaults to HTTPS. If you are not using HTTPS, you must provide the http:// prefix when specifying the platform domain name you are targeting.

2) Log in to your plaform using --basic auth.

Use command apc login --basic.

Specify your credentials:

username: admin (or whatever name you provided)
password: yourPassword

You must use the --basic flag to log in using basic authentication.

Expected results:

apc login --basic
Connecting to http://cluster-name.apcera
Username: admin
Password: **********
Login successful.

3) Use command apc target to verify that you are logged in successfully.

apc target
Targeted https://sub-domain-name.apcera-platform.io
Logged in as: "admin@apcera.me"
Current namespace: "/sandbox/admin"

APC target with Google auth login

If you are using the platform with a third-pary identity provider such as Google auth, log in as follows:

1) Use command apc target to identify your platform to APC:

apc target platform-name.domain-name.tld
Targeted https://platform-name.domain-name.tld

NOTE: APC defaults to HTTPS. In this case, HTTPS is used so you do not need to provide the http:// prefix when targeting.

2) Log in using your configured authentication provider.

On platform deployment, you will receive instructions on how to log in. Generally, this is done by creating a Google Apps domain account for your platform. To log in for the first time using Google authentication (default ID provider), issue the following APC command:

apc login

Or, to be explicit:

apc login --google

Expected results:

Connecting to https://platform-name.domain-name.tld

Now, using your browser, authenticate to your platform with Google by following these steps:

  • Browse to: https://www.google.com/device
  • Enter this code: <LOGIN-CODE>
  • Grant access to Apcera.

3) Once you have followed the above steps using your browser, return to your APC session and enter "Y" (for yes) at the prompt and you will be logged in to your platform.

4) Issue command apc target to verify that you are logged in with your email account and have a namespace.

Working with namespaces

As the name suggests, a sandbox is a place where you can play with the system without interfering with ongoing business operations, or even the sandboxes of other users. The fact that it is a namespace means that any names you create while playing in your sandbox are private to you and do not conflict with names used by other parts of the system.

Using APC

To use APC you type apc followed a command, followed by optional sub-commands, command-specific options, and global options.

apc <COMMAND> [<SUB-COMMAND>] [command-specific-options] [global-options]

For example, the following invokes the app create command to create a new app (myApp) in the "/dev/test" namespace. The app's source files reside in the folder myappfolder/ and is started immediately.

apc app create myApp --namespace /dev/test -p ./myappfolder --start

Global Command-line Options

APC provides the following global command-line options:

--ascii Causes tables to be output as ASCII, regardless of locale.
--batch Disables interactive input for a command. Use the APC_BATCH environment variable to implicitly set this mode.
-h, --help View help for a specific command.
--html Causes tables to be output as HTML.
--json Output will be JSON (and also batch).
-l When used with any apc <resource> list command, includes UUID, FQN, and version of each resource in output. See Finding a resource's UUID with APC.
--markdown Causes tables to be output as Markdown, if --html was not also specified.
-ns, --namespace Runs your command in the specified namespace.
-q, --silent Disables all input and output. Automatically enables batch mode.
--trace Dumps contents of APC server requests to apc.log. See Using APC's trace mode for details.
-vv, --verbose Increases output in some commands.
-vvv, --very-verbose Increases output further in some commands.

Using APC Help

APC provides online help for all commands, sub-commands, and options.

  • To list all top-level APC commands and global options type apc help (or apc):

      $ apc help
      APC is Continuum's command-line tool.
      Usage: apc COMMAND [command-specific-options]
      Global flags:
        -ns, --namespace NS   - Run your command in a different namespace.
        ...
      Subcommands:
        app              - Manage apps
        capsule          - Manage capsules
        changelog        - See APC's recent product updates
        ...
    
  • To display a command's available sub-commands and command-specific options type apc help <command> (or apc <command>). For example, the following displays help for the app subcommand:

      $ apc help app
      Usage: apc app <subcommand> <required args> [optional args]
      The 'app' command performs operations on apps running in Continuum.
      Subcommands:
        attract      - Establish a scheduling affinity between apps
        connect      - Connects to an app via SSH
        console      - Connect to a temporary capsule for your app
        ...
    
  • To display help and command-specific options for a subcommand enter apc help <command> <subcommand>. The following displays help for the app connect command.

      $ apc help app connect
      Usage: apc app connect <app-name>
    
      The 'app connect' command opens an SSH session with the specified app. If your
      environment is proxied, you should target your platform over HTTPS
      before connecting to a app container.
      ...
      Command options:
        -instance, --instanceid UUID      - UUID of the instance to connect to
    

Updating APC

APC is automatically updated if it is out of date with the platform version.

To check for APC updates, use the following command:

apc update

You can also check the versions of APC and the targeted platform using the following commands:

apc version

apc cluster info

Finding a resource's UUID with APC

Each resource in a cluster is assigned a universally unique identifier (UUID). To find a resource's UUID, call the apc <resource> list command with the -l flag, where <resource> is any resource type, such as app, job, or package. This option includes each resource's UUID in the command output, as well as each resource's FQN and version number. For example:

apc app list -l
Working in "/sandbox"...
╭─────────────────────────┬────────┬─...┬──────────────────────────────────────╮
│ FQN                     │ Status │ ...│ UUID                                 │
├─────────────────────────┼────────┼─...┼──────────────────────────────────────┤
│ job::/sandbox::todo-app │ ready  │ ...│ d730f723-55b5-490d-9f4b-fea14e9bdddc │
│ job::/sandbox::website  │ ready  │ ...│ 0367816b-153f-43fa-9f7d-e1cc6dabf44d │
╰─────────────────────────┴────────┴─...┴──────────────────────────────────────╯