Installing Apcera CE on Azure

Follow these steps to deploy the Apcera Platform on Azure:

  1. Complete prerequisites
  2. Install the platform
  3. Create the platform
  4. Deploy the platform
  5. Verify deployment
  6. Bootstrap the platform
  7. Manage the platform
  8. Use the platform

Complete prerequisites

This section lists the prerequisites for deploying the Apcera Platform Community Edition on Azure.

Review Azure requirements

Before you begin, please familiarize yourself with the requirements to install the Apcera Platform Community Edition on Azure.

Download and install apcera-setup tool

If you have not done so already, download the apcera-setup tool. If necessary, review the requirements for using the tool.

Install the tool and run it to verify your environment.

Install the platform

Run the command apcera-setup install to install the platform.

For example, on Mac you run the command $ ./apcera-setup install.

Alternatively, you can use the command apcera-setup config to begin the installation process with detailed interaction. See additional installation method for more information.


When you run the apcera-setup tool for the first time, you must accept the Registration agreement.

[ Registration ]
Installation and use of the Apcera Platform Community Edition software requires that you have registered, accepted the terms and conditions, and downloaded the software from Do you agree to the terms and conditions? [Y/n]

Press enter [Y] to acknowledge and proceed with the installation.

Version check

When you run the apcera-setup tool, you will be notified if there is a newer version available for download:

[ Version Check ]
Checking for latest version....
[WARNING] A more recent version of apcera-setup is available for download from

See updating the apcera-setup tool for more details.

Cluster Location

First you are prompted to specify the domain name for your cluster:

[ Cluster Location ]
Where will your Apcera Platform cluster be located?
[0] As a sub-domain of
[1] In a domain that you provide (DNS will be configured after the create step)
Enter your selection [0]:

You have two options: use an Apcera-provided domain or provide your own registered domain name. Typically you simply press enter to use the default Apcera-provided domain.

Enter 0 (default) to use an Apcera-provided domain

If you choose option 0, you are notified that the platform domain will be <sub-domain-name>, and prompted to "Enter your sub-domain." The sub-domain-name is a user-defined string between 5 and 63 characters that must be unique in our DNS server. See Configuring DNS for guidance.

Enter 1 to use your own domain

If you choose option 1, you must enter a registered domain name. At the conclusion of the apcera-setup config process, the apcera-setup tool prompts you to configure DNS. See Configuring DNS for guidance.

HTTPS Configuration

Next you are prompted to specify the mode of communications for your cluster:

[ HTTPS Configuration ]
For HTTPS communication within the cluster a certificate is required. You can provide your own certificate or have the Apcera Platform generate a self-signed certificate.
[0] Have the Apcera Platform generate a self-signed certificate
[1] Provide my own certificate
[2] Do not use a certificate (only insecure HTTP communication is available within the cluster)
Enter your selection [0]:
Please add and trust the HTTPS certificate at "certs/cert.crt".
See for more details.
Have you added/trusted the HTTPS certificate? [Y/n]

You have three options for configuring HTTPS:

Enter 0 (default) to use a self-signed HTTPS certificate.

After making this selection, you should trust the SSL certificate. Once you have trusted the certicate, enter Y at the "Have you trusted the HTTPS certificate?" prompt to complete the HTTPS configuration process.

Enter 1 to use HTTPS and provide your own SSL certificate.

See Configuring HTTPS for more information on using your own certificate.

Enter 2 to not use HTTPS

If you don't want to use HTTPS, choose option 2 at the prompt. See not using HTTPS for more information.

Provider Configuration

Next you are prompted to enter your infrastructure provider:

[ Provider Configuration ]
[0] vmware_desktop
[1] virtualbox
[2] aws
[3] vsphere
[4] openstack
[5] azure
[6] googlecloud
Enter your provider [5]:

Enter 5 to choose the Azure provider. Next you are prompted to provide information about your Azure subscription, including your subscription ID, tenant ID, and client (application) ID and secret.

Azure subscription ID []: b7f88853-35bc-408d-a371-4ec2128ab885
Azure tenant ID []: 91507b4c-f875-471a-85eb-96a68c398d66
Azure client ID []: 5783b333-dc3b-4c81-b6a1-9dbc42efa8e4
Azure client secret []: GUJjQCbqiXVaCUtQihc9a0b

Refer to the Azure documentation for help obtaining these values.

Azure Configuration

Next you are prompted to provide information about your Azure configuration. You can choose to have apcera-setup create the required resource group, storage account, virtual network, subnet and security group for you, or manually configure those components. If you choose auto-create mode you will only be prompted to select the geographic location for your cluster:

[ Azure Configuration ]
[0] Auto-create resource group, storage account, virtual network, subnet and security group
[1] Manual configuration
Enter choice [0]: 0
[0] Central US
[1] East US
[2] East US 2
[3] North Central US
[4] South Central US
[5] West US
[6] North Europe
[7] West Europe
[8] East Asia
[9] Southeast Asia
[10] Japan East
[11] Japan West
[12] Brazil South

If you choose manual configuration, you will be prompted for the following information:

[ Azure Configuration ]
[0] Auto-create resource group, storage account, virtual network, subnet and security group
[1] Manual configuration
Enter choice [0]: 1
Azure resource group [apcera-setup-0123456789]:
Azure storage account [aebyqvxqqesa]:
Azure storage container [aebyqvxqqe-sc]:
Azure network security group [aebyqvxqqe-nsg]:
Azure virtual network name [aebyqvxqqe-vn]:
Azure subnet [aebyqvxqqe-subnet]:

See Configuration requirements for Azure for details on configuring these resources.

Cluster Configuration

Next you are prompted to specify the following cluster information, some of which is optional:

Number of Instance Managers

Specify the number of Instance Managers [1]:

Your applications are deployed and executed on one or more Instance Managers (IMs). You can specify 1 (default) or more IMs. Each IM runs on a separate VM.

For most use cases, Apcera recommends 2 IMs. For larger deployments, 3 or more IMs may be used. Note that there is no hard limit on the number of IMs you can run, but for local deployments running more than 5 IMs may not be possible due to hardware limits.

Zabbix Monitoring

Optionally you can deploy an additional host for cluster monitoring purposes:

Enable a Zabbix monitoring host for this cluster? [y/N]

If you enter y (yes), the cluster will be deployed with a monitoring host that includes the Zabbix server and database for monitoring cluster hosts. You will be prompted to create credentials for the admin and guest users:

Enable a Zabbix monitoring host for this cluster? [y/N] y
Zabbix admin user []: admin
Zabbix admin password []: ENTER-PASSWORD
Zabbix guest user []: guest
Zabbix guest password []: ENTER-PASSWORD

Path to public SSH key (optional)

If you want to be able to SSH into the VM hosts, enter the full local path to your public key. See Generating SSH Key Pair for Apcera CE. Note that you cannot use the default SSH key (apcera-setup ssh) with Azure.

Path to a public key for SSH access to the cluster using other clients
(Enter 'none' if you only want to use SSH via apcera-setup ssh) [none]:

You can only provide a custom SSH key the first time you deploy an instance of the platform.

Admin User Configuration

Next you are prompted to enter one or more username(s) and password(s):

[ User Configuration ]
Desired username [admin]:
Password: *****
Confirm Password: *****
Would you like to create another administrative user? [y/N]

By default your cluster is configured to use basic authentication. Enter the username (default is admin) and password for the admin user.

Optionally you can create additional admin users. Any user you create here is made a member of the admin policy role and thereby granted full access to the platform. To later add or remove admin users, you must run apcera-setup config again and redeploy the cluster (apcera-setup deploy).

If you are deploying the platform for others to use, for secure authentication Apcera recommends that you enable Google OAuth2 integration (see below) and use that to grant user access.

Google OAuth2 Configuration (optional)

By default your cluster uses basic authentication. Optionally, you can configure Google Auth as the identity provider.

[ Google OAuth2 Configuration ]
In order to enable Google OAuth2 for your cluster, you must create a project with Google at to get your API keys.

Enable Google OAuth2 integration?  [y/N]

To use Google Auth, you must create a Google project and obtain OAuth2 client IDs that you provide to apcera-setup, and create the necessary policy to grant user access. See Configuring Google Auth for Apcera CE for details.

Nameserver Configuration (DNS)

Next you are prompted to enter the primary and secondary DNS servers:

Enter your DNS server []:
Enter your secondary DNS server []:

Generally you can just accept the defaults. Or, if you are providing your own domain, you can specify one or both DNS servers. See Configuring DNS for more information.

Diagnostic and usage data (optional)

Lastly, and optionally, you can help Apcera improve the apcera-setup tool for installing the Community Edition by automatically sending anonymized diagnostic and usage data. See data we collect for details.

Would you like to help Apcera improve by sending anonymized diagnostic and usage data? [Y/n]

If you want to opt-out, type n and press enter.

Create the platform

If you are using the apcera-setup install workflow, the apcera-setup create process begins automatically.

The next step is to provision the platform infrastructure by running the command apcera-setup create.

For example, on Mac you run the command $ ./apcera-setup create.

This command provisions the EC2 instance hosts, generates the SSH keys, registers DNS and presents you with the DNS token, and generates the deployment configuration file (config.json) in the working directory.

Creating a VPC, subnet, and security group for Apcera Setup...
Orchestrator instance type: t2.small
Centrals instance type: t2.medium
IMs instance type: m4.large
IMs instance type: m4.large
Creating VMs for the Apcera Platform...

[ Preparing Templates ]

[ Creating VMs ]
Provisioning VM 1 of 4: "my-apcera-setup-vm-orchestrator-644861380"...
Provisioning VM 2 of 4: "my-apcera-setup-vm-central-1-644861380"...
Provisioning VM 3 of 4: "my-apcera-setup-vm-im-1-644861380"...
Provisioning VM 4 of 4: "my-apcera-setup-vm-im-2-644861380"...

[ Configuring VMs ]
[WARNING] Sensitive connection credentials are stored in "config.json". Please store this file securely.

[ Configuring DNS ]
Registering DNS...
DNS service registered ""
DNS Update Token Used: c99c304b-XXXX-4440-xxxx-8c6d7ff5ffff
NOTE: Please record your token.  It will be required to re-use your sub-domain name at a later time.
Waiting for domain ( to update

If you used your own domain, you are prompted to configure DNS. Follow the on-screen instructions to set up the A records for the base domain and wildcard domain using the hostname and IP address of the HTTP router.

To verify successful creation, you should see the following output from the apcera-setup tool:

[ Creation Complete ]
All set. Command to try next: "apcera-setup deploy".

Deploy the platform

If you are using the apcdera-setup install workflow, the deploy process begins automatically.

Next, run the command apcera-setup deploy to deploy the latest Apcera Platform software release.

For example, on Mac you run the command $ ./apcera-setup deploy.

This command downloads the latest Apcera release from the cloud and deploys your platform.

To deploy a specific release (other than the latest), use the -r flag with the release file or URL as the argument.

For example, to deploy an Apcera release bundle you have saved to your local computer:

./apcera-setup deploy -r release-2.0.0.tar.gz

The deployment process proceeds as follows:

$ ./apcera-setup deploy
[ Apcera Setup - Deploy ]
Deploying the Apcera Platform to cluster VMs...

[ Preparing Deploy ]
Validating VM state...

[ Deploying Cluster ]
Orchestrator IP: [ 10.0.50.xx]
Generating cluster.conf...
Uploading cluster.conf...
Cleaning up old releases before the deploy...
Deploying... Depending on your connection speed and configuration, this may take 20 min. or more. Check "logs/apcera-setup.log" for details...

If you encounter an error, check the /logs/apcera-setup.log file in the working directory. See also troubleshooting.

Once the platform is successfully deployed, you see output similar to the following:

[ Downloading APC ]
Downloading "apc.gz" to "/Users/user/apcera-setup/apc.gz"...
Downloaded 100.0% (4mb of 4mb)
[ Validating HTTPS Certificate ]

[ Registering NFS Provider ]
Targeting ""

[ Validating Cluster Images ]

[ Deploy Complete ]

| Full documentation on Apcera Platform is available at:
| The web console can be accessed at:
| Target and log into the cluster with:
|   apc target
|   apc login --basic

All steps are completed. If you have not bootstrapped your cluster before, you should run: "apcera-setup bootstrap".

The apcera-setup tool downloads the APC client to your local working directory. You do not need to install it.

Verify deployment

To verify successful deployment, complete the following system checks:

1) Access the web console:

  • Console URL (assuming you used HTTPS and the Acpera DNS):
  • Log in using basic auth (or Google auth if you enabled it)

NOTE: If you are using Firefox, you need to load the cert.

2) Target your platform and log in using APC:

  • Target your platform: apc target
  • Log in using basic auth: apc login --basic (or Google auth if you enabled it)

NOTE: The default is HTTPS. If you are using HTTP, you need to specify it, for example: apc target

See troubleshooting if you cannot log in to your cluster using the web console or APC.

3) Connect to the Orchestrator host using SSH (optional, if enabled):

Optionally, if you enabled SSH, you can test SSH access to the Orchestrator host as follows:

First, get the public IP address of the Orchestrator host and run the following command:

apcera-setup status

Then connect to the Orchestrator host:

$ ssh ubuntu@

Where the IP address is the IP address of your Orchestrator host.

You should see the following (enter "yes" at the prompt):

The authenticity of host ' (' can't be established.
ECDSA key fingerprint is SHA256:S2oB25G697krLpzb4bIWvo4JVp126vbyv9PgxuuGnLQ.
Are you sure you want to continue connecting (yes/no)? yes
Warning: Permanently added '' (ECDSA) to the list of known hosts.

Run the following command to view the cluster configuration file:

cat cluster.conf

Type exit to quit the SSH session.


Bootstrap the platform

If you are using the apcera-setup install workflow, the bootstrap process begins automatically.

Lastly, run the apcera-setup bootstrap command to import a base set of packages and create service providers for NFS, MySQL, and PostgreSQL. See bootstrapping the platform for details.

For example, on Mac you run the command $ ./apcera-setup bootstrap.

The bootstrapping process is required and may take 30 minutes or more. You only need to bootstrap your platform the first time you deploy it.

Manage the platform

Use the apcera-setup tool to manage your Apcera Platform, including getting deployment info and status, managing the infrastructure, and maintaining Apcera Platform software.

When the platform is successfully deployed and bootstrapped, you see the output of the apcera-setup status and apcera-setup info commands:

[ Apcera Setup - Status ]
Please wait a moment while we query your cluster...

[ Cluster Status ]
│ Provider │ Status       │
│ azure    │ Bootstrapped │

[ Machine Status ]
│ Role         │ Name                                          │ IP Address                 │ Status  │
│ Orchestrator │ waylon-apcera-setup-vm-orchestrator-139916696 │, │ running │
│ Central      │ waylon-apcera-setup-vm-central-1-139916696    │,  │ running │
│ IM           │ waylon-apcera-setup-vm-im-1-139916696         │, │ running │
│ IM           │ waylon-apcera-setup-vm-im-2-1330938714        │,   │ running │

Access any of your VMs using your preferred ssh client by logging in as the user "ubuntu" (e.g. ssh ubuntu@<ip>) using the key located at "/Users/user/apcera-setup/".
[ Apcera Setup - Info ]
Web Console:
Users: admin
DNS Token: 7f5e4bba-XxxX-4567-xXXx-8240100bb103
Provider: azure
Number of Centrals: 1
Number of IMs: 2
SSH Access: See "apcera-setup status" for details about how to access your cluster via ssh
Installation complete.

Use the platform

If you are new to Apcera, a good place to start is the Apcera Developer Portal.

If you are already familiar with the Apcera Platform, you may want to advance your skills by going through some additional tutorials.