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.
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.
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
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
APC Environment Variables
APC reads from the following environment variables to modify it's behavior.
||Path to directory in which to save the
||Set to disable interactive input globally.|
||Proxy URL, if your networking environment requires a proxy for HTTP.|
||Comma-separated list of domains that override
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]
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
apc login --basic.
Specify your credentials:
admin (or whatever name you provided)
You must use the
--basicflag to log in using basic authentication.
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: "firstname.lastname@example.org" 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:
Or, to be explicit:
apc login --google
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:
- 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.
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:
||Causes tables to be output as ASCII, regardless of locale.|
||Disables interactive input for a command. Use the
||View help for a specific command.|
||Causes tables to be output as HTML.|
||Output will be JSON (and also batch).|
||When used with any
||Causes tables to be output as Markdown, if
||Runs your command in the specified namespace.|
||Disables all input and output. Automatically enables batch mode.|
||Dumps contents of APC server requests to apc.log. See Using APC's trace mode for details.|
||Increases output in some commands.|
||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 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
$ 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
$ 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
APC is automatically updated if it is out of date with the platform version. To manually check for APC updates, use the
apc update command:
$ apc update To continue, APC must update to version 2.6.0 at https://api.example.com/v1/apc/download/darwin_amd64/apc.gz. Downloading new APC binary... 100% Creating backup of APC (/usr/local/bin/apc.bak)... done Overwriting old binary... done APC successfully installed!
If APC determines that you have the latest version then no update is installed. You can force an update with the
apc update --force
You can check the version of APC you are using and its build number with the
apc version command:
$ apc version 2.6.0 (f7fab07)
Viewing cluster information
apc cluster info command to check the version and build number of your Apcera cluster. The command also displays the cluster's administrator name and email, if available.
apc cluster info Apcera Platform Version: 2.6.0 Build ID: f7fab07 Apcera Admin Name: John Smith Apcera Admin Email: email@example.com
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
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 │ ╰─────────────────────────┴────────┴─...┴──────────────────────────────────────╯