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 freeand 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.
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:
The following are optional, but recommended:
example.com, managed by AWS Route53 DNS, to use as the top-level domain of the cluster;
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 theto get an AWS API key with the required permissions.
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.
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.
baresoil-server.conf.json and using it to auto-generate a Terraform configuration file called
The raise-cluster sub-command is shorthand for running
terraform plan and then
terraform apply in the same directory as
main.tf 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.
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.
The build-image command performs the following steps:
packer buildin the server image directory, and tags the built AMI with an image name.
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.
Once you have run build-image successfully to build a Baresoil AMI, you can deploy the AMI to your cluster to run it.
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 themethod for rolling, zero-downtime deployments on AWS using Terraform:
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.
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.
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
This command runs "terraform destroy", which can be INCREDIBLY DESTRUCTIVE.
This step cannot be undone; use caution.
Next: deploy an app to your server.