EC2 Configuration and Deployment

Perfect Assistant supports deployment of projects to Amazon EC2 server instances. To begin, first create a new EC2 Deployment Configuration from either the Index window templates area or from within a project's "Project Deployments" view.

When a new EC2 deployment configuration is created it will appear in the Index window's "Deployments" section. Creating a new configuration will automatically open the configuration editor window where the deployment can be configured.

AWS Tools Installation

If you already have the AWS command line tools installed on your machine and available in your $PATH, then Perfect Assistant will use that version and be able to take advantage of any existing configuration information such as IAM access keys, and preferred EC2 regions.

If the AWS command line tools are not installed, Perfect Assistant will prompt you to install them when you first open an EC2 deployment configuration. This prompt will automatically install a local copy of the AWS tools. The tools will be installed to "~/Library/Perfect/PerfectAssistant/aws/".

Settings

The configurable window toolbar permits quick access back to the Index window, as well as the ability to open the AWS dashboard site in your browser, create new instances, and refresh the list of EC2 instances.

After creating a new EC2 configuration it is given a default generic name. Click the "Set" button to the right of the title to enable the text area in which you can assign it a new descriptive name. Press the enter key to provisionally commit the change. You must save the configuration for the any changes to be fully committed.

Below the title is the main settings view. In this view you can select the desired deployment region, input your IAM credentials, SSH private key, and select the instances to which associated projects will be deployed.

Region

The "Region" popup list presents all of the available EC2 deployment regions. Changing the region will alter the list of available instances onto which the configuration can deploy.

Credentials and Keys

IAM credentials and SSH private keys must be obtained from AWS. Clicking the "Add…" button next to the "IAM Credentials" popup will bring up a sheet in which you can enter your Access Key ID, Secret Access Key, and enter a descriptive name for this set of credentials.

Perfect Assistant will read and write to the standard AWS tools credentials file. If you have already entered AWS credentials using these command line tools then you will see then present in the IAM credentials popup list. Adding new credentials to this list within Perfect Assistant will enable them to be used with these command line tools as well.

A valid AWS obtained private key file is required for the system to deploy to your instances. Ensure that the key file is only readable by your macOS user account. If this file is readable by any other accounts then SSH operations to your instances will fail.

Instances

Once a valid set of IAM credentials has been selected, the "Available Instances" view can be used to select or create new instances to deploy to. Perfect Assistant EC2 deployments rely on a specific base image for instances. Because of this, only instances with the tag "isPerfect=1" will be listed in this view. When new instances are created through Perfect Assistant this tag will automatically be added to them.

Clicking the "Add…" button next to this list will bring up a sheet permitting new instances to be created.

In this sheet, enter the number of new instances to create, select the instance type/size, key pair, and subnet. Select one or more security groups for the new instances. It is vital that the security groups permit at least SSH access for the machine from which you will be deploying.

Select the base image which will be used for the new instances. It is important to select a base image which matches the Swift toolchain version that you will be using for project builds. The exact base images shown in this list will vary by region and in cases where newer or improved images are added to the AWS system. Each of these images are crafted specifically for Swift deployment. Each is based on Ubuntu 16.04.

Clicking "Launch" will close the sheet and trigger the new instance creation. As it can take a short bit for new instances to fully start, please be patient. Clicking the "Refresh" button will refresh the instances list and the new instances will appear once they have fully launched.

Newly created instances will not have a name associated with them. Double click in the Name column for the instance you wish to name or re-name. Enter the new name and press enter. Renaming instances will take place immediately.

Finally, select one or more instances for deployment by checking the "Selected" checkbox in the first column of the list. This will mark the instances as being deployment destinations for the configuration. Once that is done, save the configuration to commit all the changes.

Project Association

Once the deployment configuration is fully set up it can be associated with project. You will see the deployment configuration in the project editor's "Project Deployments" "+" popup menu. Selecting a configuration from the menu will associate it with the project. Save the project changes. When choosing to deploy the associated project the chosen deployment configurations will be utilized.