polecat v0.0.6

Polecat

Small, nimble, and powerful serverless deployments.

Rationale

There are a number of other serverless deployment systems available, but none offered convenience when deploying "application variants". They also tend to lack support for team based operations. An application variant is a deployment of the same code to a number of instances, each with different configurations. This kind of deployment can happen in enterprise software when a different server is launched for each tenant.

Limitations

The current biggest limitation is that Polecat is restricted to AWS. In the future I'd very much like to expand this to include other major providers.

Architecture

Polecat starts with the concept of an "application". An application is based on a single set of code, and is normally something considered independant of other applications. A company may have, for example, two main products; each of these would be considered an application.

The next level down is the "deployment". A deployment is specific to an application, and represents a variation on configuration. Each deployment has its own domain name, and is effectively considered a unique website. The only connection between deployments is that they share a code base.

Each deployment may provision one or more databases, connected specifically to that deployment.

TODO: Talk about how the code and bundle are separated and considered to operate. Administration commands, etc.

Usage

To start using Polecat, you'll need:

• An AWS account.

• Access to your AWS account using the CLI.

Initialise Polecat and Application

Polecat needs two things in order to be used:

1. A storage location for code bundles, and application uploads.

2. An administrator account.

The storage location is currently limited to an S3 bucket. This bucket can be used on a per application basis, or a single bucket may be used to house multiple applications across an organisation. Both options may be created by specifying the bucket name to to the initialisation command.

To initialise an application, including a storage bucket and an administrator account, run:

polecat init <application> [bucket]

Here, <application> is the application name to initialise. [bucket] is an optional argument describing the name of the bucket to use to house uploads. If omitted, the value is taken to be the same as the application, creating a "per-application" bucket scenario. For example, to create an application called myapp using a bucket of the same name, run:

polecat init myapp

If this is the first time the initialisation command has been run, a new file will be created in the current directory called administrator.credentials. It includes the administrator AWS credentials to be used to administer Polecat. Place them in your ~/.aws/credentials file, and enable them when you wish to administer Polecat. It's recommended to create application specific users/groups for regular usage.

Create Group and User

For everyday interaction with applications, especially when in a team environment, being able to limit the actions of a particular user can be invaluable. Some users we trust to redeploy a limited group of applications. Others we may trust to run administration commands on certain applications, but not to redeploy. The variations on this theme are many and varied.

Polecat supports creation of users and groups to partition authorization across applications and deployments.

In order to provide access to applications and deployments, create a new group:

polecat create-group <name> [application, application, ...]

For example, to create a new group called developers with access to our application from above, myapp, we can run:

polecat create-group developers myapp

To create new users, we can use:

polecat create-user <username> [group, group, ...]

This will create users initially assigned to a set of groups. For example, to create a new user named harry that is currently assigned to the developers group, run:

polecat create-user harry developers

This will create a new file called harry.credentials, containing the AWS credentials to be used by the new user. Send these to the user in question; they need to enable these credentials when interacting with Polecat.

Create Application Deployment

Applications represent the code associated with a project, but by themselves cannot be deployed. To support variations on configuration associated with applications, Polecat provides "deployments". Each deployment provides for different environment variables, and can be deployed to various versions of your code.

To create a new deployment, use:

polecat create-deployment <name>

For example, to create a production deployment of our application we could run:

polecat create-deployment production

Upload Code/Bundle

polecat upload-code production

polecat upload-bundle production web/dist

Publish Deployment

To publish your deployment to the world, you'll need:

• A Route53 domain name.

• A certificate managed with ACM.

Please refer to Amazon's documentation surrounding both of the above. Assuming we've created a domain for myapp.com, and a certificate for myapp.com, we can declare that we wish to publish the production deployment of our application with:

polecat publish production myapp.com

Deploy All Changes

Up until now we've not actually created any new infrastructure on AWS; instead we've declared to Polecat how we want our infrastructure to be created. To request all changed be created we can run:

polecat deploy

After a minute or two you should be able to navigate to myapp.com to see your site.

Create Deployment Database

Most modern applications require databases. Polecat provides a convienience command to create a new database and link it to a deployment via environmental values:

polecat create-db production

Note: To deploy the new database secret you will need to rerun polecat deploy.

Add Secrets

To add secret values exposed through the environment:

polecat create-secret production MY_SECRET my-value

Note: To deploy the new secret you will need to rerun polecat deploy.

Costs and Usage

Polecat provides a convenient command to review your usage and costs for applications.

polecat cost-usage

TODO

• Bug when deploying without any secrets.