Installing Apcera CE on Local VMs

Follow these steps to install the Apcera Platform Community Edition locally using either of the supported virtual machine (VM) providers: VirtualBox (default) or VMware Desktop (Fusion and Workstation).

  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 locally.

Review the requirements

Please review the list of requirements before you deploy the Apcera Platform Community Edition on VirtualBox or VMware Fusion or Workstation.

Create SSH key (optional)

During the installation process you are prompted to provide an SSH key so you can access the cluster hosts.

If you don't specify a custom key, the apcera-setup tool will generate and register an SSH key pair for you. Alternatively you can provide your own custom SSH public key. See Configuring SSH Access for complete details.

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

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.

Registration

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 https://www.apcera.com/setup/. 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
https://www.apcera.com/setup

See updating the apcera-setup tool for more details.

Cluster Location

First you are prompted to specify a domain name.

[ DNS Configuration ]
Where will your Apcera Platform cluster be located?
[0] As a sub-domain of apcera-platform.io
[1] In a domain that you provide (DNS will be configured after the create step)
Enter your selection [0]: 
Your cluster domain will be <sub-domain-name>.apcera-platform.io
Enter your sub-domain []: dolphin (for example)

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, your platform domain is <sub-domain-name>.apcera-platform.io, where 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 more information.

In the above example, the domain name will be dolphin.apcera-platform.io.

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, you are prompted 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 http://docs.apcera.com/setup/apcera-setup-certs/ 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.

See Configuring HTTPS for more information on this option.

After making this selection, you must trust the SSL certificate. Once you have trusted the certificate, 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 choose the infrastructure provider. Supported local providers are virtualbox (default) and vmware_desktop, which supports either VMWare Fusion (Mac OS X) or Workstation (Windows).

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

Press Enter to choose VirtualBox as the provider, or enter 0 to use VMware Fusion or Workstation as the provider. If you are using a different provider, refer to those instructions.

If you choose VirtualBox, you are prompted to enter the network device number for the bridged network configuration:

[0] en0: Wi-Fi (AirPort)
Enter network device number for VirtualBox bridged network configuration [0]: 

Generally you can just press enter to accept the default (0), or specify a different network bridge to use.

Cluster Configuration

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

[ Cluster Configuration ]
Your applications are deployed and executed on the Instance Managers.  Each IM runs on a separate VM.
Specify the number of Instance Managers [1]: 
Path to a public key for ssh access to the cluster (optional) []: 
Desired username [admin]: 
Password: ******
Confirm Password: ******
Would you like to create another administrative user? [y/N] 
Enter your DNS server [8.8.8.8]: 
Enter your secondary DNS server [8.8.4.4]: 
Enable Google OAuth2 integration? [y/N] 
Would you like to help Apcera improve by sending anonymized diagnostic and usage data? [Y/n] 

Number of Instance Managers

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 1 or 2 IMs may not be possible due to hardware limits.

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. Or you can simply press enter and have the apcera-setup tool create an SSH key for you. See Generating SSH Key Pair for Apcera CE.

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 Username(s) and Password(s)

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 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 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 integration (optional)

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

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 on enabling Google Auth.

Nameserver Configuration (DNS)

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

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

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)

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

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.

Configuration Complete

This completes the configuration. The next step is to create the cluster.

Create the platform

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

Once you have configured the platform you run the command apcera-setup create to create the infrastructure.

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

The apcera-setup tool downloads the Apcera Platform VM images (Orchestrator and Base), provisions the VM hosts on the specified provider (virtualbox or vmware_desktop), registers the domain name with our DNS server, and generates the deployment configuration file (config.json) in the working directory. The entire process takes approximately 15 minutes, possibly longer depending on your network speed. If you get an error, check the /logs/apcera-setup.log file also in the working directory. See also troubleshooting.

Once the creation process completes, 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.

During provisioning, a VM window will open as each VM is launched. Ignore any instructions that may appear within the VM windows. You can minimize (but do not close) any such window. Note that if you are using VMware and you are prompted to upgrade the virtual hardware of the VM, please do NOT choose to upgrade. See this troubleshooting topic for details.

Deploy the platform

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

Next, run the command apcera-setup deploy to deploy the latest version of the Apcera Platform.

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

This command downloads the latest Apcera release from the cloud and deploys the platform on your chosen provider VMs. This process will take approximately 30 minutes to complete, but may take longer depending on your network speed. See other deployment options if necessary.

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

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

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 both of the following system checks:

1) Access the web console:

  • Console URL (assuming you used HTTPS and the Acpera DNS): https://console.sub-domain-name.apcera-platform.io
  • 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 sub-domain-name.apcera-platform.io
  • 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 http://sub-domain-name.apcera-platform.io.

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

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 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.

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.