cpl 1.0.0 → 1.0.1

checksums.yaml

@@ -1,7 +1,7 @@
 ---
 SHA256:
-  metadata.gz: 410e8bfdc923cabc36b900bb6cc3bb98e586cc2789579ec01cc33fe9c9c39fe1
-  data.tar.gz: a7428c35cff0dabcd1c68469561b82e2c3f24282b92dba9b1eeeb94c51d9d654
+  metadata.gz: da0cd8b4b3f57a141b2a148a35555069f4ff4135803e4ae95932cd3887e3a567
+  data.tar.gz: dab258fecce6a5948374057418959d736915ab69f84593e1b189c148f62f00be
 SHA512:
-  metadata.gz: 9c09fb9477e7dd638220e4ad711161a176daab7e82ed7224d584b6617989e3dd789ae5f66eb75e0086bdcd9690d680e2de668b5698ce322184ecdd23522835a3
-  data.tar.gz: 82f3a8aaf6b465850f9b577c5f7aed1b8b4313bf0224d52f058fc94e17f334a9cb9f51bb2638600c150184714fb254c2edeea1bb1f77b40a976fe20d0db11b54
+  metadata.gz: 31c5cfe13e647abf6f34f6b021c808c220db07a48cd223d0d277ad7814ab0942961a7b75c63d89c3c109e7ca670d478285e5289fdb9fe64ccd828917b7fccf22
+  data.tar.gz: 926431c8d7fb4c5f8ba7930a3a156d70718dcce6eb1c717e9859f5a8546900266e4267cee7c755ca4c99612fb1b574a7cbfdd6ca23a2fd5483c1eb3c743a83db

data/.gitignore

@@ -2,6 +2,7 @@
 .DS_Store
 
 /.bundle/
+/.vscode/
 /.yardoc
 /_yardoc/
 /coverage/

data/Gemfile.lock

@@ -1,7 +1,7 @@
 PATH
   remote: .
   specs:
-    cpl (1.0.0)
+    cpl (1.0.1)
       debug (~> 1.7.1)
       dotenv (~> 2.8.1)
       psych (~> 5.1.0)
@@ -25,7 +25,7 @@ GEM
     hashdiff (1.0.1)
     iniparse (1.5.0)
     io-console (0.6.0)
-    irb (1.6.4)
+    irb (1.7.0)
       reline (>= 0.3.0)
     json (2.6.3)
     overcommit (0.60.0)
@@ -41,7 +41,7 @@ GEM
     rainbow (3.1.1)
     rake (13.0.6)
     regexp_parser (2.6.2)
-    reline (0.3.4)
+    reline (0.3.5)
       io-console (~> 0.5)
     rexml (3.2.5)
     rspec (3.12.0)
@@ -83,7 +83,7 @@ GEM
       simplecov_json_formatter (~> 0.1)
     simplecov-html (0.12.3)
     simplecov_json_formatter (0.1.4)
-    stringio (3.0.6)
+    stringio (3.0.7)
     thor (1.2.2)
     timecop (0.9.6)
     unicode-display_width (2.4.2)

data/README.md

@@ -13,49 +13,57 @@ _A playbook for migrating from [Heroku](https://heroku.com) to [Control Plane](h
 
 [![Gem](https://badge.fury.io/rb/cpl.svg)](https://badge.fury.io/rb/cpl)
 
-This playbook shows how to move "Heroku apps" to "Control Plane workloads" via an open-source `cpl` CLI on top of Control Plane's `cpln` CLI.
+This playbook shows how to move "Heroku apps" to "Control Plane workloads" via an open-source `cpl` CLI on top of
+Control Plane's `cpln` CLI.
 
-Heroku provides a UX and CLI that enables easy publishing of Ruby on Rails and other apps. This ease of use comes via many "Heroku" abstractions and naming conventions.
-Control Plane, on the other hand, gives you access to raw cloud computing power. However, you need to know precisely how to use it.
+Heroku provides a UX and CLI that enables easy publishing of Ruby on Rails and other apps. This ease of use comes via
+many "Heroku" abstractions and naming conventions.
 
-To simplify migration to and usage of Control Plane for Heroku users, this repository provides a **concept mapping** and a **helper CLI** based on templates to save lots of day-to-day typing (and human errors).
+Control Plane, on the other hand, gives you access to raw cloud computing power. However, you need to know precisely how
+to use it.
 
-1. [Key features](#key-features)
-2. [Concept mapping](#concept-mapping)
+To simplify migration to and usage of Control Plane for Heroku users, this repository provides a **concept mapping** and
+a **helper CLI** based on templates to save lots of day-to-day typing (and human errors).
+
+1. [Key Features](#key-features)
+2. [Concept Mapping](#concept-mapping)
 3. [Installation](#installation)
-4. [Example CLI flow for application build/deployment](#example-cli-flow-for-application-builddeployment)
-5. [Example project modifications for Control Plane](#example-project-modifications-for-control-plane)
+4. [Example CLI Flow for Application Build/Deployment](#example-cli-flow-for-application-builddeployment)
+   - [Initial Setup and Deployment](#initial-setup-and-deployment)
+   - [Promoting Code Upgrades](#promoting-code-upgrades)
+5. [Example Project Modifications for Control Plane](#example-project-modifications-for-control-plane)
 6. [Environment](#environment)
 7. [Database](#database)
-8. [In-memory databases](#in-memory-databases)
-9. [Scheduled jobs](#scheduled-jobs)
-10. [CLI commands reference](#cli-commands-reference)
+8. [In-memory Databases](#in-memory-databases)
+9. [Scheduled Jobs](#scheduled-jobs)
+10. [CLI Commands Reference](#cli-commands-reference)
 11. [Mapping of Heroku Commands to `cpl` and `cpln`](#mapping-of-heroku-commands-to-cpl-and-cpln)
 12. [Examples](#examples)
-13. [Migrating Postgres database from Heroku infrastructure](/docs/postgres.md)
-14. [Migrating Redis database from Heroku infrastructure](/docs/redis.md)
+13. [Migrating Postgres Database from Heroku Infrastructure](/docs/postgres.md)
+14. [Migrating Redis Database from Heroku Infrastructure](/docs/redis.md)
+15. [Tips](/docs/tips.md)
 
-## Key features
+## Key Features
 
-- A `cpl` command to complement the default Control Plane `cpln` command with "Heroku style scripting." The Ruby source can serve as inspiration for your own scripts.
+- A `cpl` command to complement the default Control Plane `cpln` command with "Heroku style scripting." The Ruby source
+  can serve as inspiration for your own scripts.
 - Easy to understand Heroku to Control Plane conventions in setup and naming.
 - **Safe, production-ready** equivalents of `heroku run` and `heroku run:detached` for Control Plane.
 - Automatic sequential release tagging for Docker images.
-- A project-aware CLI which enables working on multiple projects.
+- A project-aware CLI that enables working on multiple projects.
 
-## Concept mapping
+## Concept Mapping
 
 On Heroku, everything runs as an app, which means an entity that:
 
-1. Runs code from a Git repo
-2. Runs several process types, as defined in the `Procfile`
-3. Has dynos, which are Linux containers that run these process types
-4. Has add-ons, including the database and other services
-5. Has common environment variables
-
-On Control Plane, we can map a Heroku app to a GVC (Global Virtual Cloud). Such a cloud consists of workloads, which can be anything that can run as a container.
+- runs code from a Git repository.
+- runs several process types, as defined in the `Procfile`.
+- has dynos, which are Linux containers that run these process types.
+- has add-ons, including the database and other services.
+- has common environment variables.
 
-**Mapping of Concepts:**
+On Control Plane, we can map a Heroku app to a GVC (Global Virtual Cloud). Such a cloud consists of workloads, which can
+be anything that can run as a container.
 
 | Heroku           | Control Plane                               |
 | ---------------- | ------------------------------------------- |
@@ -66,54 +74,61 @@ On Control Plane, we can map a Heroku app to a GVC (Global Virtual Cloud). Such
 | _staging env_    | _GVC (app)_ in staging _organization_       |
 | _production env_ | _GVC (app)_ in production _organization_    |
 
-On Heroku, dyno types are specified in the `Procfile` and configured via the CLI/UI; add-ons are configured only via the CLI/UI.
+On Heroku, dyno types are specified in the `Procfile` and configured via the CLI/UI; add-ons are configured only via the
+CLI/UI.
+
 On Control Plane, workloads are created either by _templates_ (preferred way) or via the CLI/UI.
 
 For the typical Rails app, this means:
 
-| Function          | Examples             | On Heroku     | On Control Plane                                                                                                  |
-| ----------------- | -------------------- | ------------- | ----------------------------------------------------------------------------------------------------------------- |
-| web traffic       | `rails`, `sinatra`   | `web` dyno    | workload with app image                                                                                           |
-| background jobs   | `sidekiq`, `resque`  | `worker` dyno | workload with app image                                                                                           |
-| db                | `postgres`, `mysql`  | add-on        | external provider or can be set up for development/testing with Docker image (lacks persistence between restarts) |
-| in-memory db      | `redis`, `memcached` | add-on        | external provider or can be set up for development/testing with Docker image (lacks persistence between restarts) |
-| special something | `mailtrap`           | add-on        | external provider or can be set up for development/testing with Docker image (lacks persistence between restarts) |
+| Function        | Examples             | On Heroku     | On Control Plane                                                                                                  |
+| --------------- | -------------------- | ------------- | ----------------------------------------------------------------------------------------------------------------- |
+| web traffic     | `rails`, `sinatra`   | `web` dyno    | workload with app image                                                                                           |
+| background jobs | `sidekiq`, `resque`  | `worker` dyno | workload with app image                                                                                           |
+| db              | `postgres`, `mysql`  | add-on        | external provider or can be set up for development/testing with Docker image (lacks persistence between restarts) |
+| in-memory db    | `redis`, `memcached` | add-on        | external provider or can be set up for development/testing with Docker image (lacks persistence between restarts) |
+| others          | `mailtrap`           | add-on        | external provider or can be set up for development/testing with Docker image (lacks persistence between restarts) |
 
 ## Installation
 
-**Note:** `cpl` CLI is configured either as a Ruby gem, [`cpl`](https://rubygems.org/gems/cpl) install or a local clone. For information on the latter, see [CONTRIBUTING.md](CONTRIBUTING.md).
-
-1. Install `node` (required for Control Plane CLI).
-2. Install `ruby` (required for these helpers).
-3. Install Control Plane CLI (adds `cpln` command) and configure credentials by running command `cpln login`.
+1. Install [Node.js](https://nodejs.org/en) (required for Control Plane CLI).
+2. Install [Ruby](https://www.ruby-lang.org/en/) (required for these helpers).
+3. Install Control Plane CLI (adds `cpln` command) and configure credentials.
 
 ```sh
 npm install -g @controlplane/cli
 cpln login
 ```
 
-## Tips
+4. Install Heroku to Control Plane `cpl` CLI, either as a [Ruby gem](https://rubygems.org/gems/cpl) or a local clone.
+   For information on the latter, see [CONTRIBUTING.md](CONTRIBUTING.md).
 
-Do not confuse the `cpl` CLI with the `cpln` CLI. The `cpl` CLI is the Heroku to Control Plane playbook CLI. The `cpln` CLI is the Control Plane CLI.
-
-- For each Git project that you want to deploy to Control Plane, copy project-specific configs to a `.controlplane` directory at the top of your project. `cpl` will pick those up depending on which project
-  folder tree it runs. Thus, this automates running several projects with different configs without explicitly switching configs.
+```sh
+gem install cpl
+```
 
-5. Create a `Dockerfile` for your production deployment. See [this example](https://github.com/shakacode/react-webpack-rails-tutorial/blob/master/.controlplane/Dockerfile).
+**Note:** Do not confuse the `cpl` CLI with the `cpln` CLI. The `cpl` CLI is the Heroku to Control Plane playbook CLI.
+The `cpln` CLI is the Control Plane CLI.
 
-## Example CLI flow for application build/deployment
+## Example CLI Flow for Application Build/Deployment
 
 **Notes:**
 
-1. `myapp` is an app name defined in the `.controlplane/controlplane.yml` file, such as `ror-tutorial` in [this `controlplane.yml` file](https://github.com/shakacode/react-webpack-rails-tutorial/blob/master/.controlplane/controlplane.yml).
-2. Other files in the `.controlplane/templates` directory are used by the `cpl setup-app` and `cpl apply-template` commands.
+- `my-app` is an app name defined in the `.controlplane/controlplane.yml` file, such as `ror-tutorial` in
+  [this `controlplane.yml` file](https://github.com/shakacode/react-webpack-rails-tutorial/blob/master/.controlplane/controlplane.yml).
+- Other files in the `.controlplane/templates/` directory are used by the `cpl setup-app` and `cpl apply-template`
+  commands.
 
 ### Initial Setup and Deployment
 
-Before the initial setup, add the templates for the app to `.controlplane/controlplane.yml`, using the `setup` key:
+For each Git project that you want to deploy to Control Plane, copy project-specific configs to a `.controlplane/`
+directory at the top of your project. `cpl` will pick those up depending on which project folder tree it runs. Thus,
+this automates running several projects with different configs without explicitly switching configs.
+
+Before the initial setup, add the templates for the app to `.controlplane/controlplane.yml`, using the `setup` key, e.g.:
 
 ```yaml
-myapp:
+my-app:
   setup:
     - gvc
     - postgres
@@ -123,59 +138,61 @@ myapp:
     - sidekiq
 ```
 
-Note how the templates correspond to files in the `.controlplane/templates` directory.
+Note how the templates correspond to files in the `.controlplane/templates/` directory.
+
+Then create a `Dockerfile` for your deployment. See
+[this example](https://github.com/shakacode/react-webpack-rails-tutorial/blob/master/.controlplane/Dockerfile).
 
 ```sh
 # Provision infrastructure (one-time-only for new apps) using templates.
-cpl setup-app -a myapp
+cpl setup-app -a my-app
 
-# Build and push image with auto-tagging "myapp:1_456".
-cpl build-image -a myapp --commit 456
+# Build and push image with auto-tagging, e.g., "my-app:1_456".
+cpl build-image -a my-app --commit 456
 
 # Prepare database.
-cpl run:detached rails db:prepare -a myapp --image latest
+cpl run:detached -a my-app --image latest -- rails db:prepare
 
 # Deploy latest image.
-cpl deploy-image -a myapp
+cpl deploy-image -a my-app
 
 # Open app in browser.
-cpl open -a myapp
+cpl open -a my-app
 ```
 
-### Promoting code upgrades
+### Promoting Code Upgrades
 
 ```sh
-# Build and push new image with sequential image tagging, e.g. 'ror-tutorial_123'
-cpl build-image -a ror-tutorial
+# Build and push new image with sequential tagging, e.g., "my-app:2".
+cpl build-image -a my-app
 
-# OR
-# Build and push with sequential image tagging and commit SHA, e.g. 'ror-tutorial_123_ABCD'
-cpl build-image -a ror-tutorial --commit ABCD
+# Or build and push new image with sequential tagging and commit SHA, e.g., "my-app:2_ABC".
+cpl build-image -a my-app --commit ABC
 
-# Run database migrations (or other release tasks) with latest image,
-# while app is still running on previous image.
+# Run database migrations (or other release tasks) with latest image, while app is still running on previous image.
 # This is analogous to the release phase.
-cpl run:detached rails db:migrate -a ror-tutorial --image latest
+cpl run:detached -a my-app --image latest -- rails db:migrate
 
-# Deploy latest image to app
-cpl deploy-image -a ror-tutorial
+# Deploy latest image.
+cpl deploy-image -a my-app
 ```
 
-## Example project modifications for Control Plane
+## Example Project Modifications for Control Plane
 
 _See this for a complete example._
 
-To learn how to migrate an app, we recommend that you first follow along with [this example project](https://github.com/shakacode/react-webpack-rails-tutorial).
+To learn how to migrate an app, we recommend following along with
+[this example project](https://github.com/shakacode/react-webpack-rails-tutorial).
 
-1. Create the `.controlplane` directory at the top of your project and copy files from the `templates` directory of this repo to
-   something as follows:
+1. Create the `.controlplane/` directory at the top of your project and copy files from the `templates/` directory of
+   this repository to something as follows:
 
 ```sh
 app_main_folder/
   .controlplane/
     Dockerfile          # Your app's Dockerfile, with some Control Plane changes.
     controlplane.yml
-    entrypoint.sh       # App-specific, edit as needed.
+    entrypoint.sh       # App-specific - edit as needed.
     templates/
       gvc.yml
       memcached.yml
@@ -185,9 +202,12 @@ app_main_folder/
       sidekiq.yml
 ```
 
-The example [`.controlplane` directory](https://github.com/shakacode/react-webpack-rails-tutorial/tree/master/.controlplane) already contains these files.
+The example
+[`.controlplane/` directory](https://github.com/shakacode/react-webpack-rails-tutorial/tree/master/.controlplane)
+already contains these files.
 
-2. Edit your `controlplane.yml` file as needed. For example, see [this `controlplane.yml` file](https://github.com/shakacode/react-webpack-rails-tutorial/blob/master/.controlplane/controlplane.yml).
+2. Edit your `controlplane.yml` file as needed. For example, see
+   [this `controlplane.yml` file](https://github.com/shakacode/react-webpack-rails-tutorial/blob/master/.controlplane/controlplane.yml).
 
 ```yaml
 # Keys beginning with "cpln_" correspond to your settings in Control Plane.
@@ -195,11 +215,10 @@ The example [`.controlplane` directory](https://github.com/shakacode/react-webpa
 aliases:
   common: &common
     # Organization name for staging (customize to your needs).
-    # Production apps will use a different Control Plane organization, specified below, for security.
+    # Production apps will use a different organization, specified below, for security.
     cpln_org: my-org-staging
 
     # Example apps use only one location. Control Plane offers the ability to use multiple locations.
-    # TODO -- allow specification of multiple locations
     default_location: aws-us-east-2
 
     # Configure the workload name used as a template for one-off scripts, like a Heroku one-off dyno.
@@ -216,52 +235,58 @@ aliases:
       - postgres
       - memcached
 
+    # Configure the workload name used when maintenance mode is on (defaults to "maintenance")
+    maintenance_workload: maintenance
+
 apps:
   my-app-staging:
     # Use the values from the common section above.
     <<: *common
   my-app-review:
     <<: *common
-    # If `match_if_app_name_starts_with` == `true`, then use this config for app names starting with this name,
+    # If `match_if_app_name_starts_with` is `true`, then use this config for app names starting with this name,
     # e.g., "my-app-review-pr123", "my-app-review-anything-goes", etc.
     match_if_app_name_starts_with: true
   my-app-production:
     <<: *common
     # Use a different organization for production.
     cpln_org: my-org-production
-    # Allows running the command `cpl promote-app-from-upstream -a my-app-production` to promote the staging app to production.
+    # Allows running the command `cpl promote-app-from-upstream -a my-app-production`
+    # to promote the staging app to production.
     upstream: my-app-staging
   my-app-other:
     <<: *common
-    # You can specify a different `Dockerfile` relative to the `.controlplane` directory (default is just "Dockerfile").
+    # You can specify a different `Dockerfile` relative to the `.controlplane/` directory (defaults to "Dockerfile").
     dockerfile: ../some_other/Dockerfile
 ```
 
-3. We recommend that you try out the commands listed in [the example](https://github.com/shakacode/react-webpack-rails-tutorial/blob/master/.controlplane/readme.md). These steps will guide you through:
-   1. Provision the GVC and workloads
-   2. Build the Docker image
-   3. Run Rails migrations, like in the Heroku release phase
-   4. Promote the lastest Docker image
+3. We recommend that you try out the commands listed in
+   [the example](https://github.com/shakacode/react-webpack-rails-tutorial/blob/master/.controlplane/readme.md).
+   These steps will guide you to the following:
+
+   1. Provision the GVC and workloads.
+   2. Build the Docker image.
+   3. Run Rails migrations, like in the Heroku release phase.
+   4. Promote the latest Docker image.
 
 ## Environment
 
 There are two main places where we can set up environment variables in Control Plane:
 
-- **In `workload/container/env`** - those are container-specific and need to be set up individually for each container.
+- **In `workload/container/env`** - those are container-specific and must be set up individually for each container.
 
-- **In `gvc/env`** - this is a "common" place to keep env vars which we can share among different workloads.
-  Those common variables are not visible by default, and we should explicitly enable them via the `inheritEnv` property.
+- **In `gvc/env`** - this is a "common" place to keep env vars which we can share among different workloads. Those
+  common variables are not visible by default, and we should explicitly enable them via the `inheritEnv` property.
 
-In general, `gvc/env` vars are useful for "app" types of workloads, e.g., `rails`, `sidekiq`, as they can easily share
-common configs (the same way as on a Heroku app). They are not needed for non-app workloads,
-e.g., `redis`, `memcached`.
+Generally, `gvc/env` vars are useful for "app" types of workloads, e.g., `rails`, `sidekiq`, as they can easily share
+common configs (the same way as on a Heroku app). They are not needed for non-app workloads, e.g., `redis`, `memcached`.
 
 It is ok to keep most of the environment variables for non-production environments in the app templates as, in general,
 they are not secret and can be committed to the repository.
 
-It is also possible to set up a Secret store (of type Dictionary), which we can reference as,
-e.g., `cpln://secret/MY_SECRET_STORE_NAME/MY_SECRET_VAR_NAME`.
-In such a case, we also need to set up an app Identity and proper Policy to access the secret.
+It is also possible to set up a Secret store (of type `Dictionary`), which we can reference as, e.g.,
+`cpln://secret/MY_SECRET_STORE_NAME/MY_SECRET_VAR_NAME`. In such a case, we must set up an app Identity and proper
+Policy to access the secret.
 
 ```yaml
 # In `templates/gvc.yml`:
@@ -281,31 +306,32 @@ spec:
           value: 'value'
         - name: MY_SECRET_LOCAL_VAR
           value: 'cpln://secret/MY_SECRET_STORE_NAME/MY_SECRET_LOCAL_VAR'
-      inheritEnv: true # To enable global env inheritance
+      inheritEnv: true # To enable global env inheritance.
 ```
 
 ## Database
 
 There are several options for a database setup on Control Plane:
 
-1. **Heroku Postgres**. It is the least recommended but simplest. We only need to provision the Postgres add-on on Heroku and
-   copy its `XXXXXX_URL` connection string. This is good for quick testing, but unsuitable for the long term.
+- **Heroku Postgres**. It is the least recommended but simplest. We only need to provision the Postgres add-on on Heroku
+  and copy its `XXXXXX_URL` connection string. This is good for quick testing but unsuitable for the long term.
 
-2. **Control Plane container**. We can set it up as a workload using one of the default [Docker Hub](https://hub.docker.com/) images.
-   However, such a setup lacks persistence between container restarts.
-   We can use this only for an example or test app
-   where the database doesn't keep any serious data and where such data is restorable.
+- **Control Plane container**. We can set it up as a workload using one of the default
+  [Docker Hub](https://hub.docker.com/) images. However, such a setup lacks persistence between container restarts. We
+  can use this only for an example or test app where the database doesn't keep any serious data and where such data is
+  restorable.
 
-3. Any other cloud provider for Postgres, e.g., Amazon's RDS can be a quick go-to. Here are [instructions for setting up a free tier of RDS.](https://aws.amazon.com/premiumsupport/knowledge-center/free-tier-rds-launch/).
+- Any other cloud provider for Postgres, e.g., Amazon's RDS can be a quick go-to. Here are
+  [instructions for setting up a free tier of RDS](https://aws.amazon.com/premiumsupport/knowledge-center/free-tier-rds-launch/).
 
 **Tip:** If you are using RDS for development/testing purposes, you might consider running such a database publicly
-accessible (Heroku actually does that for all of its Postgres databases unless they are within private spaces). Then we can connect to
-such a database from everywhere with only the correct username/password.
+accessible (Heroku actually does that for all of its Postgres databases unless they are within private spaces). Then we
+can connect to such a database from everywhere with only the correct username/password.
 
-By default, we have structured our templates to accomplish this with only a single free tier or low tier AWS RDS instance
-that can serve all your development/testing needs for small/medium applications, e.g., as follows:
+By default, we have structured our templates to accomplish this with only a single free tier or low tier AWS RDS
+instance that can serve all your development/testing needs for small/medium applications, e.g., as follows:
 
-```
+```sh
 aws-rds-single-pg-instance
   mydb-staging
   mydb-review-111
@@ -313,22 +339,22 @@ aws-rds-single-pg-instance
   mydb-review-333
 ```
 
-Additionally, we provide a default `postgres` template in this repo optimized for Control Plane and suitable
-for development purposes.
+Additionally, we provide a default `postgres` template in this repository optimized for Control Plane and suitable for
+development purposes.
 
-## In-memory databases
+## In-memory Databases
 
-E.g. Redis, Memcached.
+E.g., Redis, Memcached.
 
-For development purposes, it's useful to set those up as Control Plane workloads, as in most cases they don't keep any
-valuable data and can be safely restarted (sometimes), which doesn't affect application performance.
+For development purposes, it's useful to set those up as Control Plane workloads, as in most cases, they don't keep any
+valuable data and can be safely restarted, which doesn't affect application performance.
 
 For production purposes or where restarts are not an option, you should use external cloud services.
 
-We provide default `redis` and `memcached` templates in this repo optimized for Control Plane and suitable
-for development purposes.
+We provide default `redis` and `memcached` templates in this repository optimized for Control Plane and suitable for
+development purposes.
 
-## Scheduled jobs
+## Scheduled Jobs
 
 Control Plane supports scheduled jobs via [cron workloads](https://docs.controlplane.com/reference/workload#cron).
 
@@ -340,9 +366,9 @@ name: daily-task
 spec:
   type: cron
   job:
-    # Run daily job at 2am
+    # Run daily job at 2am.
     schedule: 0  2  *  *  *
-    # Never or OnFailure
+    # "Never" or "OnFailure"
     restartPolicy: Never
   containers:
     - name: daily-task
@@ -354,17 +380,19 @@ spec:
       image: "/org/APP_ORG/image/APP_IMAGE"
 ```
 
-A complete example can be found at [templates/daily-task.yml](templates/daily-task.yml), optimized for Control Plane and suitable for development purposes.
+A complete example can be found at [templates/daily-task.yml](templates/daily-task.yml), optimized for Control Plane and
+suitable for development purposes.
 
-You can create the cron workload by adding the template for it to the `.controlplane/templates` folder and running `cpl apply-template my-template -a my-app`, where `my-template` is the name of the template file (`my-template.yml`).
+You can create the cron workload by adding the template for it to the `.controlplane/templates/` directory and running
+`cpl apply-template my-template -a my-app`, where `my-template` is the name of the template file (e.g., `my-template.yml`).
 
 Then to view the logs of the cron workload, you can run `cpl logs -a my-app -w my-template`.
 
-## CLI commands reference:
+## CLI Commands Reference
 
 Click [here](/docs/commands.md) to see the commands.
 
-You can also run:
+You can also run the following command:
 
 ```sh
 cpl --help
@@ -372,8 +400,6 @@ cpl --help
 
 ## Mapping of Heroku Commands to `cpl` and `cpln`
 
-**`[WIP]`**
-
 | Heroku Command                                                                                                 | `cpl` or `cpln`                 |
 | -------------------------------------------------------------------------------------------------------------- | ------------------------------- |
 | [heroku ps](https://devcenter.heroku.com/articles/heroku-cli-commands#heroku-ps-type-type)                     | `cpl ps`                        |
@@ -388,5 +414,6 @@ cpl --help
 
 ## Examples
 
-1. See `examples/` and `templates/` folders of this repo.
-2. See `.controlplane` directory of this live example: [react-webpack-rails-tutorial](https://github.com/shakacode/react-webpack-rails-tutorial/tree/master/.controlplane)
+- See the `examples/` and `templates/` directories of this repository.
+- See the `.controlplane/` directory of this live example:
+  [react-webpack-rails-tutorial](https://github.com/shakacode/react-webpack-rails-tutorial/tree/master/.controlplane)

data/docs/commands.md

@@ -1,6 +1,6 @@
 <!-- NOTE: This file is automatically generated by running `script/generate_commands_docs`. Do NOT edit it manually. -->
 
-### Common Options
+## Common Options
 
 ```
 -a XXX, --app XXX         app ref on Control Plane (GVC)
@@ -9,7 +9,7 @@
 This `-a` option is used in most of the commands and will pick all other app configurations from the project-specific
 `.controlplane/controlplane.yml` file.
 
-### Commands
+## Commands
 
 ### `apply-template`
 

data/docs/tips.md

@@ -0,0 +1,177 @@
+# Tips
+
+1. [GVCs vs. Orgs](#gvcs-vs-orgs)
+2. [RAM](#ram)
+3. [Remote IP](#remote-ip)
+4. [ENV Values](#env-values)
+5. [CI](#ci)
+6. [Memcached](#memcached)
+7. [Sidekiq](#sidekiq)
+   - [Quieting Non-Critical Workers During Deployments](#quieting-non-critical-workers-during-deployments)
+   - [Setting Up a Pre Stop Hook](#setting-up-a-pre-stop-hook)
+   - [Setting Up a Liveness Probe](#setting-up-a-liveness-probe)
+8. [Useful Links](#useful-links)
+
+## GVCs vs. Orgs
+
+- A "GVC" roughly corresponds to a Heroku "app."
+- Images are available at the org level.
+- Multiple GVCs within an org can use the same image.
+- You can have different images within a GVC and even within a workload. This flexibility is one of the key differences
+  compared to Heroku apps.
+
+## RAM
+
+Any workload replica that reaches the max memory is terminated and restarted. You can configure alerts for workload
+restarts and the percentage of memory used in the Control Plane UX.
+
+Here are the steps for configuring an alert for the percentage of memory used:
+
+1. Navigate to the workload that you want to configure the alert for
+2. Click "Metrics" on the left menu to go to Grafana
+3. On Grafana, go to the alerting page by clicking on the alert icon in the sidebar
+4. Click on "New alert rule"
+5. In the "Set a query and alert condition" section, select "Grafana managed alert"
+6. There should be a default query named `A`
+7. Change the data source of the query to `metrics`
+8. Click "Code" on the top right of the query and enter `mem_used{workload="workload_name"} / mem_reserved{workload="workload_name"} * 100`
+   (replace `workload_name` with the name of the workload)
+9. There should be a default expression named `B`, with the type `Reduce`, the function `Last`, and the input `A` (this
+   ensures that we're getting the last data point of the query)
+10. There should be a default expression named `C`, with the type `Threshold`, and the input `B` (this is where you
+    configure the condition for firing the alert, e.g., `IS ABOVE 95`)
+11. You can then preview the alert and check if it's firing or not based on the example time range of the query
+12. In the "Alert evaluation behavior" section, you can configure how often the alert should be evaluated and for how
+    long the condition should be true before firing (for example, you might want the alert only to be fired if the
+    percentage has been above `95` for more than 20 seconds)
+13. In the "Add details for your alert" section, fill out the name, folder, group, and summary for your alert
+14. In the "Notifications" section, you can configure a label for the alert if you're using a custom notification policy,
+    but there should be a default root route for all alerts
+15. Once you're done, save and exit in the top right of the page
+16. Click "Contact points" on the top menu
+17. Edit the `grafana-default-email` contact point and add the email where you want to receive notifications
+18. You should now receive notifications for the alert in your email
+
+![](assets/grafana-alert.png)
+
+The steps for configuring an alert for workload restarts are almost identical, but the code for the query would be
+`container_restarts`.
+
+For more information on Grafana alerts, see: https://grafana.com/docs/grafana/latest/alerting/
+
+## Remote IP
+
+The actual remote IP of the workload container is in the 127.0.0.x network, so that will be the value of the
+`REMOTE_ADDR` env var.
+
+However, Control Plane additionally sets the `x-forwarded-for` and `x-envoy-external-address` headers (and others - see:
+https://docs.controlplane.com/concepts/security#headers). On Rails, the `ActionDispatch::RemoteIp` middleware should
+pick those up and automatically populate `request.remote_ip`.
+
+So `REMOTE_ADDR` should not be used directly, only `request.remote_ip`.
+
+## ENV Values
+
+You can store ENV values used by a container (within a workload) within Control Plane at the following levels:
+
+1. Workload Container
+2. GVC
+
+For your "review apps," it is convenient to have simple ENVs stored in plain text in your source code. You will want to
+keep some ENVs, like the Rails' `SECRET_KEY_BASE`, out of your source code. For staging and production apps, you will
+set these values directly at the GVC or workload levels, so none of these ENV values are committed to the source code.
+
+For storing ENVs in the source code, we can use a level of indirection so that you can store an ENV value in your source
+code like `cpln://secret/my-app-review-env-secrets.SECRET_KEY_BASE` and then have the secret value stored at the org
+level, which applies to your GVCs mapped to that org.
+
+Here is how you do this:
+
+1. In the upper left "Manage Org" menu, click on "Secrets"
+2. Create a secret with `Secret Type: Dictionary` (e.g., `my-secrets`) and add the secret env vars there
+3. In the upper left "Manage GVC" menu, click on "Identities"
+4. Create an identity (e.g., `my-identity`)
+5. Navigate to the workload that you want to associate with the identity created
+6. Click "Identity" on the left menu and select the identity created
+7. In the lower left "Access Control" menu, click on "Policies"
+8. Create a policy with `Target Kind: Secret` and add a binding with the `reveal` permission for the identity created
+9. Use `cpln://secret/...` in the app to access the secret env vars (e.g., `cpln://secret/my-secrets.SOME_VAR`)
+
+## CI
+
+**Note:** Docker builds much slower on Apple Silicon, so try configuring CI to build the images when using Apple
+hardware.
+
+Make sure to create a profile on CI before running any `cpln` or `cpl` commands.
+
+```sh
+CPLN_TOKEN=...
+cpln profile create default --token ${CPLN_TOKEN}
+```
+
+Also, log in to the Control Plane Docker repository if building and pushing an image.
+
+```sh
+cpln image docker-login
+```
+
+## Memcached
+
+On the workload container for Memcached (using the `memcached:alpine` image), configure the command with the args
+`-l 0.0.0.0`.
+
+To do this:
+
+1. Navigate to the workload container for Memcached
+2. Click "Command" on the top menu
+3. Add the args and save
+
+![](assets/memcached.png)
+
+## Sidekiq
+
+### Quieting Non-Critical Workers During Deployments
+
+To avoid locks in migrations, we can quiet non-critical workers during deployments. Doing this early enough in the CI
+allows all workers to finish jobs gracefully before deploying the new image.
+
+There's no need to unquiet the workers, as that will happen automatically after deploying the new image.
+
+```sh
+cpl run 'rails runner "Sidekiq::ProcessSet.new.each { |w| w.quiet! unless w[%q(hostname)].start_with?(%q(criticalworker.)) }"' -a my-app
+```
+
+### Setting Up a Pre Stop Hook
+
+By setting up a pre stop hook in the lifecycle of the workload container for Sidekiq, which sends "QUIET" to the workers,
+we can ensure that all workers will finish jobs gracefully before Control Plane stops the replica. That also works
+nicely for multiple replicas.
+
+A couple of notes:
+
+- We can't use the process name as regex because it's Ruby, not Sidekiq.
+- We need to add a space after `sidekiq`; otherwise, it sends `TSTP` to the `sidekiqswarm` process as well, and for some
+  reason, that doesn't work.
+
+So with `^` and `\s`, we guarantee it's sent only to worker processes.
+
+```sh
+pkill -TSTP -f ^sidekiq\s
+```
+
+To do this:
+
+1. Navigate to the workload container for Sidekiq
+2. Click "Lifecycle" on the top menu
+3. Add the command and args below "Pre Stop Hook" and save
+
+![](assets/sidekiq-pre-stop-hook.png)
+
+### Setting Up a Liveness Probe
+
+To set up a liveness probe on port 7433, see: https://github.com/arturictus/sidekiq_alive
+
+## Useful Links
+
+- For best practices for the app's Dockerfile, see: https://lipanski.com/posts/dockerfile-ruby-best-practices
+- For migrating from Heroku Postgres to RDS, see: https://pelle.io/posts/hetzner-rds-postgres

data/examples/circleci.yml

@@ -8,8 +8,8 @@ build-staging:
     - image: cimg/ruby:3.1-node
   resource_class: large
   environment:
-    CPLN_ORG: myorg
-    APP_NAME: myapp-staging
+    CPLN_ORG: my-org
+    APP_NAME: my-app-staging
   steps:
     - checkout
     - setup_remote_docker:
@@ -21,14 +21,13 @@ build-staging:
           cpln profile create default --token ${CPLN_TOKEN} --org ${CPLN_ORG} --gvc ${APP_NAME}
           cpln image docker-login
 
-          git clone https://github.com/shakacode/heroku-to-control-plane ~/heroku-to-control-plane
-          sudo ln -s ~/heroku-to-control-plane/cpl /usr/local/bin/cpl
+          gem install cpl
     - run:
         name: Containerize and push image
         command: cpl build-image -a ${APP_NAME}
     - run:
         name: Database tasks
-        command: cpl run:detached rails db:migrate -a ${APP_NAME} --image latest
+        command: cpl run:detached -a ${APP_NAME} --image latest -- rails db:migrate
     - run:
         name: Deploy image
         command: cpl deploy-image -a ${APP_NAME}
@@ -43,7 +42,7 @@ build-review-app:
     - image: cimg/ruby:3.1-node
   resource_class: large
   environment:
-    CPLN_ORG: my-org-name
+    CPLN_ORG: my-org
   steps:
     - checkout
     - setup_remote_docker:
@@ -65,7 +64,7 @@ build-review-app:
     - run:
         name: Provision review app if needed
         command: |
-          if ! cpl exist -a ${APP_NAME}; then
+          if ! cpl exists -a ${APP_NAME}; then
             cpl setup-app -a ${APP_NAME}
             echo "export NEW_APP=true" >> $BASH_ENV
           fi
@@ -77,9 +76,9 @@ build-review-app:
         name: Database tasks
         command: |
           if [ -n "${NEW_APP}" ]; then
-            cpl run:detached 'LOG_LEVEL=warn rails db:reset' -a ${APP_NAME} --image latest
+            cpl run:detached -a ${APP_NAME} --image latest -- LOG_LEVEL=warn rails db:reset
           else
-            cpl run:detached 'LOG_LEVEL=warn rails db:migrate' -a ${APP_NAME} --image latest
+            cpl run:detached -a ${APP_NAME} --image latest -- LOG_LEVEL=warn rails db:migrate
           fi
     - run:
         name: Deploy image

data/examples/controlplane.yml

@@ -1,47 +1,49 @@
+# Keys beginning with "cpln_" correspond to your settings in Control Plane.
+
 aliases:
   common: &common
-    # Org name for staging. (customize to your needs)
-    # Production apps will use a different Control Plane org, specified below, for security.
-    # keys beginning with CPLN correspond to your settings in Control Plane
+    # Organization name for staging (customize to your needs).
+    # Production apps will use a different organization, specified below, for security.
     cpln_org: my-org-staging
 
-    # Example apps use only location. CPLN offers the ability to use multiple locations.
-    # TODO -- allow specfication of multiple locations
+    # Example apps use only one location. Control Plane offers the ability to use multiple locations.
+    # TODO: Allow specification of multiple locations.
     default_location: aws-us-east-2
 
     # Configure the workload name used as a template for one-off scripts, like a Heroku one-off dyno.
     one_off_workload: rails
 
-    # Workloads that are application itself and are using application docker image
+    # Workloads that are for the application itself and are using application Docker images.
     app_workloads:
       - rails
       - sidekiq
 
-    # Additional "service type" workloads, using non-application docker images
+    # Additional "service type" workloads, using non-application Docker images.
     additional_workloads:
       - redis
       - postgres
       - memcached
 
-    # Configure the workload name used when maintenance mode is on (defaults to 'maintenance')
+    # Configure the workload name used when maintenance mode is on (defaults to "maintenance")
     maintenance_workload: maintenance
 
 apps:
   my-app-staging:
-    # Use the values from the common section above
+    # Use the values from the common section above.
     <<: *common
   my-app-review:
     <<: *common
-    # if match_if_app_name_starts_with == true, then use this config for app names beginning,
-    # like my-app-review-pr123 or my-app-review-anything-goes
+    # If `match_if_app_name_starts_with` is `true`, then use this config for app names starting with this name,
+    # e.g., "my-app-review-pr123", "my-app-review-anything-goes", etc.
     match_if_app_name_starts_with: true
   my-app-production:
     <<: *common
-    # Use a different org for production
+    # Use a different organization for production.
     cpln_org: my-org-production
-    # Allows running command 'cpl pipeline-promote my-app-staging' to promote the staging app to production
+    # Allows running the command `cpl promote-app-from-upstream -a my-app-production`
+    # to promote the staging app to production.
     upstream: my-app-staging
   my-app-other:
     <<: *common
-    # you can specify different dockerfile relative to .controlplane folder, default is just 'Dockerfile'
+    # You can specify a different `Dockerfile` relative to the `.controlplane/` directory (defaults to "Dockerfile").
     dockerfile: ../some_other/Dockerfile

data/lib/command/base.rb

@@ -210,7 +210,7 @@ module Command
 
       # Or special string to indicate no image available
       if matching_items.empty?
-        "#{app_name}:#{NO_IMAGE_AVAILABLE}"
+        name_only ? "#{app_name}:#{NO_IMAGE_AVAILABLE}" : nil
       else
         latest_item = matching_items.max_by { |item| extract_image_number(item["name"]) }
         name_only ? latest_item["name"] : latest_item

data/lib/command/cleanup_stale_apps.rb

@@ -51,6 +51,7 @@ module Command
 
             images = cp.image_query(app_name)["items"].filter { |item| item["name"].start_with?("#{app_name}:") }
             image = latest_image_from(images, app_name: app_name, name_only: false)
+            next unless image
 
             created_date = DateTime.parse(image["created"])
             diff_in_days = (now - created_date).to_i

data/lib/cpl/version.rb

@@ -1,5 +1,6 @@
 # frozen_string_literal: true
 
 module Cpl
-  VERSION = "1.0.0"
+  VERSION = "1.0.1"
+  MIN_CPLN_VERSION = "0.0.71"
 end

data/lib/cpl.rb

@@ -40,16 +40,57 @@ end
 module Cpl
   class Error < StandardError; end
 
-  class Cli < Thor
+  class Cli < Thor # rubocop:disable Metrics/ClassLength
     package_name "cpl"
     default_task :no_command
 
     def self.start(*args)
+      check_cpln_version
+      check_cpl_version
       fix_help_option
 
       super(*args)
     end
 
+    def self.check_cpln_version # rubocop:disable Metrics/MethodLength
+      return if @checked_cpln_version
+
+      @checked_cpln_version = true
+
+      result = `cpln --version 2>/dev/null`
+      if $CHILD_STATUS.success?
+        data = JSON.parse(result)
+
+        version = data["npm"]
+        min_version = Cpl::MIN_CPLN_VERSION
+        if Gem::Version.new(version) < Gem::Version.new(min_version)
+          ::Shell.abort("Current 'cpln' version: #{version}. Minimum supported version: #{min_version}. " \
+                        "Please update it with 'npm update -g @controlplane/cli'.")
+        end
+      else
+        ::Shell.abort("Can't find 'cpln' executable. Please install it with 'npm install -g @controlplane/cli'.")
+      end
+    end
+
+    def self.check_cpl_version # rubocop:disable Metrics/MethodLength
+      return if @checked_cpl_version
+
+      @checked_cpl_version = true
+
+      result = `gem search ^cpl$ --remote 2>/dev/null`
+      return unless $CHILD_STATUS.success?
+
+      matches = result.match(/cpl \((.+)\)/)
+      return unless matches
+
+      version = Cpl::VERSION
+      latest_version = matches[1]
+      return unless Gem::Version.new(version) < Gem::Version.new(latest_version)
+
+      ::Shell.warn("You are not using the latest 'cpl' version. Please update it with 'gem update cpl'.")
+      $stderr.puts
+    end
+
     # This is so that we're able to run `cpl COMMAND --help` to print the help
     # (it basically changes it to `cpl --help COMMAND`, which Thor recognizes)
     # Based on https://stackoverflow.com/questions/49042591/how-to-add-help-h-flag-to-thor-command

data/script/update_command_docs

@@ -46,7 +46,7 @@ file_data =
   <<~DATA
     <!-- NOTE: This file is automatically generated by running `script/generate_commands_docs`. Do NOT edit it manually. -->
 
-    ### Common Options
+    ## Common Options
 
     ```
     -a XXX, --app XXX         app ref on Control Plane (GVC)
@@ -55,7 +55,7 @@ file_data =
     This `-a` option is used in most of the commands and will pick all other app configurations from the project-specific
     `.controlplane/controlplane.yml` file.
 
-    ### Commands
+    ## Commands
 
     #{commands_str}
   DATA

data/templates/daily-task.yml

@@ -4,23 +4,24 @@ spec:
   # https://docs.controlplane.com/reference/workload#cron-configuration
   type: cron
   job:
-    # Run daily job at 2am, see cron docs
+    # Run daily job at 2am (see cron docs)
     schedule: 0  2  *  *  *
     # Never or OnFailure
     restartPolicy: Never
   containers:
     - name: daily-task
+      cpu: 50m
+      memory: 256Mi
       args:
         - bundle
         - exec
         - rails
         - db:prepare
-      cpu: 50m
       inheritEnv: true
-      image: '/org/APP_ORG/image/APP_IMAGE'
-      memory: 256Mi
+      image: "/org/APP_ORG/image/APP_IMAGE"
   defaultOptions:
     autoscaling:
+      minScale: 1
       maxScale: 1
     capacityAI: false
   firewallConfig:

data/templates/maintenance.yml

@@ -6,15 +6,16 @@ spec:
     - name: maintenance
       env:
         - name: PORT
-          value: '3000'
+          value: "3000"
         - name: PAGE_URL
-          value: ''
-      image: 'shakacode/maintenance-mode'
+          value: ""
+      image: "shakacode/maintenance-mode"
       ports:
         - number: 3000
           protocol: http
   defaultOptions:
     autoscaling:
+      minScale: 1
       maxScale: 1
     capacityAI: false
     timeoutSeconds: 60

data/templates/memcached.yml

@@ -7,15 +7,16 @@ spec:
       cpu: 3m
       memory: 10Mi
       args:
-        - '-l'
+        - "-l"
         - 0.0.0.0
-      image: 'memcached:alpine'
+      image: "memcached:alpine"
       ports:
         - number: 11211
           protocol: tcp
   defaultOptions:
     autoscaling:
       metric: latency
+      minScale: 1
       maxScale: 1
     capacityAI: false
   firewallConfig:

data/templates/postgres.yml

@@ -13,17 +13,18 @@ spec:
           value: password123
         - name: POSTGRES_USER
           value: postgres
-      image: 'postgres:13.8-alpine'
+      image: "postgres:13.8-alpine"
       ports:
         - number: 5432
           protocol: tcp
       volumes:
         - path: /var/lib/postgresql/data
           recoveryPolicy: retain
-          uri: 'scratch://postgres-vol'
+          uri: "scratch://postgres-vol"
   defaultOptions:
     autoscaling:
       metric: latency
+      minScale: 1
       maxScale: 1
     capacityAI: false
   firewallConfig:

data/templates/rails.yml

@@ -5,14 +5,15 @@ spec:
   containers:
     - name: rails
       cpu: 512m
-      inheritEnv: true
-      image: '/org/APP_ORG/image/APP_IMAGE'
       memory: 1Gi
+      inheritEnv: true
+      image: "/org/APP_ORG/image/APP_IMAGE"
       ports:
         - number: 3000
           protocol: http
   defaultOptions:
     autoscaling:
+      minScale: 1
       maxScale: 1
     capacityAI: false
     timeoutSeconds: 60

data/templates/redis.yml

@@ -6,13 +6,14 @@ spec:
     - name: redis
       cpu: 3m
       memory: 20Mi
-      image: 'redis:latest'
+      image: "redis:latest"
       ports:
         - number: 6379
           protocol: tcp
   defaultOptions:
     autoscaling:
       metric: latency
+      minScale: 1
       maxScale: 1
     capacityAI: false
   firewallConfig:

data/templates/sidekiq.yml

@@ -4,21 +4,30 @@ spec:
   type: standard
   containers:
     - name: sidekiq
+      cpu: 50m
+      memory: 256Mi
       args:
         - bundle
         - exec
         - sidekiq
-        - '-C'
+        - "-C"
         - config/sidekiq.yml
-      cpu: 50m
       inheritEnv: true
-      image: '/org/APP_ORG/image/APP_IMAGE'
-      memory: 256Mi
+      image: "/org/APP_ORG/image/APP_IMAGE"
       ports:
         - number: 7433
           protocol: http
+      lifecycle:
+        preStop:
+          exec:
+            command:
+              - pkill
+              - "-TSTP"
+              - "-f"
+              - ^sidekiq\s
   defaultOptions:
     autoscaling:
+      minScale: 1
       maxScale: 1
     capacityAI: false
   firewallConfig:

metadata

@@ -1,7 +1,7 @@
 --- !ruby/object:Gem::Specification
 name: cpl
 version: !ruby/object:Gem::Version
-  version: 1.0.0
+  version: 1.0.1
 platform: ruby
 authors:
 - Justin Gordon
@@ -9,7 +9,7 @@ authors:
 autorequire:
 bindir: bin
 cert_chain: []
-date: 2023-05-29 00:00:00.000000000 Z
+date: 2023-06-28 00:00:00.000000000 Z
 dependencies:
 - !ruby/object:Gem::Dependency
   name: debug
@@ -219,9 +219,13 @@ files:
 - bin/cpl
 - cpl
 - cpl.gemspec
+- docs/assets/grafana-alert.png
+- docs/assets/memcached.png
+- docs/assets/sidekiq-pre-stop-hook.png
 - docs/commands.md
 - docs/postgres.md
 - docs/redis.md
+- docs/tips.md
 - docs/troubleshooting.md
 - examples/circleci.yml
 - examples/controlplane.yml