Install Baresoil on Amazon AWS

This article contains instructions for setting up an autoscaling, high-availability Baresoil cluster on Amazon AWS, using your own AWS account. Uses the EC2, S3, and RDS services to create a private, load-balanced PaaS based on Ubuntu Linux 16.04 LTS.

This article helps you set up a load-balanced, autoscaling service distributed over multiple cloud servers. If you intend to run Baresoil on a single machine, follow the instructions for setting up a standalone Baresoil server.


The Baresoil CLI includes support for quickly setting up a customizable Baresoil cluster on Amazon AWS. It uses the free Terraform and Packer tools by Hashicorp to provision a Virtual Private Cloud in your AWS account and set up a security-hardened Baresoil cluster backed by the EC2, RDS, S3, and Route53 services. You can inspect and customize each step of the process, and retain complete control over your cloud resources.

At the end of the process, you will have a multi-AZ (availability zone), autoscaling Baresoil cluster accessible via a top-level Route53 DNS domain name. If your AWS account contains an SSL certificate for the wildcard top-level domain name, the service will be secured over TLS (i.e., HTTPS). The Baresoil CLI can then be used to log into the new cluster, and create and deploy applications that are served at subdomains of the top-level domain, like the demo server

The cluster consists of one or more web-facing EC2 instances in an Autoscaling Group behind an Elastic Load Balancer, an RDS cluster running Postgres, and S3 buckets to store immutable blobs and application logs. Where applicable, all resources are provisioned within a new Virtual Private Cloud (VPC) created for the cluster. The following diagram shows a typical cluster setup as created by the Baresoil CLI.

Default cloud service infrastructure created by Baresoil.
Default cloud service infrastructure created by Baresoil.

A cluster only has to be set up once, and can host multiple applications served at different domain names. It can also be destroyed with a single command if necessary. As of August 2017, it takes approximately 24 minutes to set up an autoscaling Baresoil cluster from scratch in us-east-1.


You will need the following:

  • node.js version 6 or higher (8 preferred),
  • Terraform version 0.9 or higher, to manage cloud infrastructure,
  • Packer version 1.0.1 or higher, to build cloud machine images,
  • OpenSSH for Linux and MacOS, or Win32-OpenSSH for Windows, and
  • an Amazon AWS account and API key.

The following are optional, but recommended:

  • a top-level domain name, like, managed by AWS Route53 DNS, to use as the top-level domain of the cluster;
  • a wildcard SSL/TLS certificate for your domain, which can be issued for free using AWS Certificate Manager for use on AWS. The certificate must include all top-level domains you wish to use, as well as their wildcard subdomains.

The AWS access key that you use must either have the AdministratorAccess security policy attached, or adequate permissions to manage EC2, RDS, CloudWatch, VPC, and S3 resources. If you have a top-level domain, the API key must also have Route53 and ACM permissions.

Visit the IAM Console to get an AWS API key with the required permissions.

Install via npm

Once you have installed all the requirements above, you can install Baresoil with the aws provider. Baresoil depends on provider modules to adapt its low-level functionality to different cloud providers and execution environments.

The command below installs the base server and the aws provider module on your system.

npm install -g baresoil baresoil-provider-aws

Linux and MacOS users may have to run npm install commands with sudo, and Windows users may require an administrator-elevated shell.

Create a new cluster configuration

Bootstrap a new cluster configuration by running the following command in an empty directory.

baresoil-server init --provider aws

Running this command will start an interactive shell session that will prompt for various configuration parameters that can customize the type of AWS resources used, which in turn affect the cost of running the cluster.

Accepting the default values will result in the smallest supported cluster size being created.

This command will create a master configuration file for your cluster called baresoil-server.conf.json, as well as editable templates for setting up an Ubuntu Linux virtual machine.

The contents of this directory contain the configuration and state of your cluster, and should be backed up and treated as any other data containing configuration secrets.

To revisit or change your answers at any later time, run baresoil-server configure in the same directory.

Raise the cluster

Baresoil uses Terraform to make changes to cloud infrastructure using your API key. It does this by reading the master configuration in baresoil-server.conf.json and using it to auto-generate a Terraform configuration file called terraform/

The raise-cluster sub-command is shorthand for running terraform plan and then terraform apply in the same directory as

baresoil-server raise-cluster

The file should not be edited manually, but other Terraform files placed in the same directory will be automatically executed when raise-cluster is run.

This command runs "terraform apply", which changes cloud infrastructure and can incur fractional cloud billing charges.

If the Terraform apply fails for any reason, you can refresh your cluster's state by running terraform refresh in the terraform directory, and then terraform apply to try to apply the transformation again.

Build an image

With a raised and prepared cluster, you can finally build a server image for the cluster. This is a repeatable step that generates an Amazon Machine Image (AMI) containing the currently configured Baresoil runtime using Packer.

The build-image command performs the following steps:

  1. Generates a server image in a clean directory, consisting of Baresoil source files and server configuration files.
  2. Runs packer build in the server image directory, and tags the built AMI with an image name.
baresoil-server build-image

This command runs "packer build", which changes cloud infrastructure, can take several minutes to run, and can incur cloud billing charges.

Building an image can take several minutes.

Deploy an image

Once you have run build-image successfully to build a Baresoil AMI, you can deploy the AMI to your cluster to run it.

baresoil-server deploy-image

This command runs "terraform apply", which changes cloud infrastructure, can take several minutes to run, and can incur cloud billing charges.

New server AMIs only have to be deployed for Baresoil server or base operating system updates. Baresoil programs do not need new server AMIs for updates, and are updated using the "baresoil deploy" command.

You can also rollback to previous server images in your account if anything goes wrong. Simply select an earlier AMI from the interactive list presented by deploy-image.

Baresoil uses the create_before_destroy method for rolling, zero-downtime deployments on AWS using Terraform:

  1. Create a new Autoscaling Group (ASG) with the new AMI and wait for it to become healthy.
  2. When the new ASG is healthy, attach it to the ELB load balancer.
  3. Drain existing connections out of the old ASG, and destroy it when empty.

If the new AMI fails to become healthy for any reason (e.g., a configuration problem), it is not attached to the load balancer, and any existing web nodes are not affected.

Start using your cluster

Once you have run deploy-image successfully, you can start using your Baresoil cluster at either the top-level domain you configured it with, or the DNS hostname of the ELB printed at the end of the deploy-image command.

Tear down the cluster

Once you are finished using your cluster, you can safely destroy any cloud resources allocated to it by running teardown-cluster to stop being charged for them by AWS.

Terraform can automatically destroy most resources created as part of the raise-cluster steps. The teardown-cluster is shorthand for running terraform destroy in the terraform folder.

baresoil-server teardown-cluster

This command runs "terraform destroy", which can be INCREDIBLY DESTRUCTIVE.

This step cannot be undone; use caution.

Next: deploy an app to your server.