# polecat > Small, nimble, serverless applications. Latest version **0.0.6** (published 2019-02-24) · 0 weekly downloads ## Install ```sh npm install polecat pnpm add polecat yarn add polecat bun add polecat ``` Provides the commands `polecat`, `polecat-es`. ## Health **Score 10/100 (F)** — status: abandoned. Positive: no vulnerabilities. Warnings: low downloads; no types; no esm support; low quality score; pre 1.0. Negative: abandoned; low maintenance score. ## Facts | | | |---|---| | Version | 0.0.6 | | Published | 2019-02-24 | | First published | 2018-04-14 | | Weekly downloads | 0 | | TypeScript types | none | | Module format | CommonJS | | Dependencies | 5 | | Unpacked size | 140.7 KB | | Known vulnerabilities | 0 (+1 in 1 direct dependencies) | | Install scripts | no | | Author | Luke Hodkinson | | Maintainers | furious.luke | ## Links - npm: https://www.npmjs.com/package/polecat - npm.io page: https://npm.io/package/polecat ## Dependencies (5) - [table](https://npm.io/package/table.md) ^5.1.1 - [aws-sdk](https://npm.io/package/aws-sdk.md) ^2.373.0 - [find-up](https://npm.io/package/find-up.md) ^3.0.0 - [commander](https://npm.io/package/commander.md) ^2.19.0 - [cli-table2](https://npm.io/package/cli-table2.md) ^0.2.0 ## Recent versions - 0.0.6 (latest) — 2019-02-24 - 0.0.5 — 2019-02-20 - 0.0.4 — 2019-02-17 - 0.0.3 — 2019-02-15 - 0.0.2 — 2019-02-01 - 0.0.1 — 2019-02-01 - 0.0.0 — 2019-01-29 - 0.1.0 — 2018-04-14 ## README # 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: ```bash polecat init [bucket] ``` Here, `` 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: ```bash 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: ```bash polecat create-group [application, application, ...] ``` For example, to create a new group called `developers` with access to our application from above, `myapp`, we can run: ```bash polecat create-group developers myapp ``` To create new users, we can use: ```bash polecat create-user [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: ```bash 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: ```bash polecat create-deployment ``` For example, to create a `production` deployment of our application we could run: ```bash polecat create-deployment production ``` ### Upload Code/Bundle ```bash polecat upload-code production ``` ```bash 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: ```bash 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: ``` bash 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: ``` bash 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: ``` bash 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. ``` bash polecat cost-usage ``` # TODO * Bug when deploying without any secrets. --- _Source: https://npm.io/package/polecat · Machine-readable twin of the npm.io package page. Health data is recomputed on every publish._