cpl 1.1.2.rc.0 → 1.2.0

checksums.yaml

@@ -1,7 +1,7 @@
 ---
 SHA256:
-  metadata.gz: bd0eff627240313d5202ff74368af8fff67483bcf0769f52f9c923a0839bfd73
-  data.tar.gz: a31c430587ecfce5cc1e7ede82ce31a0c91aec07de401fa849d18f75035dc4f1
+  metadata.gz: 711286ef49686f6c51df2a94c533b3df94f4d71d3fb6018b6ed61c210593dd47
+  data.tar.gz: '085357faac6b5b27e493049b34c27debab21fa19950af21548fe11889140b557'
 SHA512:
-  metadata.gz: 770a3ab110f7b5b7049103c50350044805ed74c1ffedf61249d9696c94877fba43cd2bef031f6d9fd2dd70f2e29e2f970cd2d32cecadd6d7a2eaa3048bd493eb
-  data.tar.gz: ec006511deb5b41610f9d4780e02c1265eddfde523f95e3c7c373ef787039c3f5cb9a99c0132da020cd649029ea6e355b37f51fb3d4035381b10724c2ac4a4d4
+  metadata.gz: ac229234f4919d8e1b3485095476ef0fddac04573d8dd03aba6a3737fd5e90b319538e04c51d98e5f33f244fe304c519d949a624a377bbc9ee9067754a0c71dd
+  data.tar.gz: 0ba5203d4f8539dde89a2eb5a52dc92c2098d11bb1914002cd57628081465d08e9842f47546da563bc18edda17fbf12101bfefca8fdcee4088825c0e56ee0fa0

data/.github/workflows/rspec.yml

@@ -36,5 +36,5 @@ jobs:
         uses: actions/upload-artifact@master
         if: always()
         with:
-          name: coverage-report
+          name: coverage-report-${{ github.run_id }}-${{ matrix.os }}-${{ matrix.ruby }}
           path: coverage

data/CHANGELOG.md

@@ -14,11 +14,44 @@ Changes since the last non-beta release.
 
 _Please add entries here for your pull requests that are not yet released._
 
+### Fixed
+
+- Fixed issue where `info` command does not respect `CPLN_ORG` env var. [PR 88](https://github.com/shakacode/heroku-to-control-plane/pull/88) by [Rafael Gomes](https://github.com/rafaelgomesxyz).
+- Fixed issues with running `cpl --version` and `cpl --help` where no configuration file exists. [PR 100](https://github.com/shakacode/heroku-to-control-plane/pull/100) by [Mostafa Ahangarha](https://github.com/ahangarha).
+- Fixed issue where `delete` command fails to delete apps with volumesets. [PR 123](https://github.com/shakacode/heroku-to-control-plane/pull/123) by [Rafael Gomes](https://github.com/rafaelgomesxyz).
+
+### Added
+
+- Added `--org` option to all commands. [PR 88](https://github.com/shakacode/heroku-to-control-plane/pull/88) by [Rafael Gomes](https://github.com/rafaelgomesxyz).
+- Added option to set the app with a `CPLN_APP` env var. [PR 88](https://github.com/shakacode/heroku-to-control-plane/pull/88) by [Rafael Gomes](https://github.com/rafaelgomesxyz).
+- Show `org` and `app` on every command excluding `info`, `version`, `maintenance`, `env`, `ps`, and `latest_image`. [PR 94](https://github.com/shakacode/heroku-to-control-plane/pull/94) by [Mostafa Ahangarha](https://github.com/ahangarha).
+- Added option to only use `CPLN_ORG` and `CPLN_APP` env vars if `allow_org_override_by_env` and `allow_app_override_by_env` configs are set to `true` in `controlplane.yml`. [PR 109](https://github.com/shakacode/heroku-to-control-plane/pull/109) by [Rafael Gomes](https://github.com/rafaelgomesxyz).
+- Added `CPLN_LOCATION` env variable and `--location` option for `apply-template`, `ps`, `run`, `run:detached`. [PR 105](https://github.com/shakacode/heroku-to-control-plane/pull/105) by [Mostafa Ahangarha](https://github.com/ahangarha).
+- Added `generate` command for creating basic Control Plane configuration directory. [PR 116](https://github.com/shakacode/heroku-to-control-plane/pull/116) by [Mostafa Ahangarhga](https://github.com/ahangarha).
+- Added `--trace` option to all commands for more detailed logs. [PR 124](https://github.com/shakacode/heroku-to-control-plane/pull/124) by [justin808](https://github.com/justin808)
+- Added better error message to check the org name in case of a 403 error. [PR 124](https://github.com/justin808) by [justin808](https://github.com/justin808)
+
+### Changed
+
+- `--org` option now takes precedence over `CPLN_ORG` env var, which takes precedence over `cpln_org` from `controlplane.yml`. [PR 88](https://github.com/shakacode/heroku-to-control-plane/pull/88) by [Rafael Gomes](https://github.com/rafaelgomesxyz).
+- Renamed `setup` config into `setup_app_templates`. [PR 112](https://github.com/shakacode/heroku-to-control-plane/pull/112) by [Mostafa Ahangarha](https://github.com/ahangarha).
+
 ## [1.1.2] - 2023-10-17
+
 ### Fixed
 
 - Fixed failed build on MacOS by adding platform flag and fixed multiple files in yaml document for template. [PR 81](https://github.com/shakacode/heroku-to-control-plane/pull/81) by [justin808](https://github.com/justin808).
 
+### Added
+
+- Added `open-console` command to open the app console on Control Plane. [PR 83](https://github.com/shakacode/heroku-to-control-plane/pull/83) by [Rafael Gomes](https://github.com/rafaelgomesxyz).
+- Added option to set the org with a `CPLN_ORG`/`CPLN_ORG_UPSTREAM` env var. [PR 83](https://github.com/shakacode/heroku-to-control-plane/pull/83) by [Rafael Gomes](https://github.com/rafaelgomesxyz).
+- Added `--verbose` option to all commands for more detailed logs. [PR 83](https://github.com/shakacode/heroku-to-control-plane/pull/83) by [Rafael Gomes](https://github.com/rafaelgomesxyz).
+
+### Changed
+
+- Calling `cpl` with no command now shows the help menu. [PR 83](https://github.com/shakacode/heroku-to-control-plane/pull/83) by [Rafael Gomes](https://github.com/rafaelgomesxyz).
+
 ## [1.1.1] - 2023-09-23
 
 ### Fixed
@@ -84,7 +117,9 @@ _Please add entries here for your pull requests that are not yet released._
 
 - Initial release
 
-[Unreleased]: https://github.com/shakacode/heroku-to-control-plane/compare/v1.1.0...HEAD
+[Unreleased]: https://github.com/shakacode/heroku-to-control-plane/compare/v1.1.2...HEAD
+[1.1.2]: https://github.com/shakacode/heroku-to-control-plane/compare/v1.1.1...v1.1.2
+[1.1.1]: https://github.com/shakacode/heroku-to-control-plane/compare/v1.1.0...v1.1.1
 [1.1.0]: https://github.com/shakacode/heroku-to-control-plane/compare/v1.0.4...v1.1.0
 [1.0.4]: https://github.com/shakacode/heroku-to-control-plane/compare/v1.0.3...v1.0.4
 [1.0.3]: https://github.com/shakacode/heroku-to-control-plane/compare/v1.0.2...v1.0.3

data/CONTRIBUTING.md

@@ -12,12 +12,6 @@ git clone https://github.com/shakacode/heroku-to-control-plane
 alias cpl="~/projects/heroku-to-control-plane/bin/cpl"
 ```
 
-Or set the path of the Ruby gem in your Gemfile.
-
-```ruby
-gem 'cpl', path: '~/projects/heroku-to-control-plane'
-```
-
 ## Linting/Testing
 
 Before committing or pushing code, be sure to:
@@ -36,6 +30,8 @@ overcommit --install
 
 ## Debugging
 
+1. Use the `--verbose` option to see more detailed logs.
+2. Use the `--trace` option to see full logging of HTTP requests. Warning, this will display keys to your logs or console.
 1. Add a breakpoint (`debugger`) to any line of code you want to debug.
 2. Modify the `lib/command/test.rb` file to trigger the code you want to test. To simulate a command, you can use
    `Cpl::Cli.start` (e.g., `Cpl::Cli.start(["deploy-image", "-a", "my-app-name"])` would be the same as running

data/Gemfile.lock

@@ -1,7 +1,7 @@
 PATH
   remote: .
   specs:
-    cpl (1.1.2.rc.0)
+    cpl (1.2.0)
       debug (~> 1.7.1)
       dotenv (~> 2.8.1)
       psych (~> 5.1.0)
@@ -24,8 +24,8 @@ GEM
     dotenv (2.8.1)
     hashdiff (1.0.1)
     iniparse (1.5.0)
-    io-console (0.6.0)
-    irb (1.8.3)
+    io-console (0.7.1)
+    irb (1.11.0)
       rdoc
       reline (>= 0.3.8)
     json (2.6.3)
@@ -36,15 +36,15 @@ GEM
     parallel (1.22.1)
     parser (3.2.0.0)
       ast (~> 2.4.1)
-    psych (5.1.1.1)
+    psych (5.1.2)
       stringio
     public_suffix (5.0.1)
     rainbow (3.1.1)
     rake (13.0.6)
-    rdoc (6.5.0)
+    rdoc (6.6.2)
       psych (>= 4.0.0)
     regexp_parser (2.6.2)
-    reline (0.3.9)
+    reline (0.4.1)
       io-console (~> 0.5)
     rexml (3.2.5)
     rspec (3.12.0)
@@ -86,7 +86,7 @@ GEM
       simplecov_json_formatter (~> 0.1)
     simplecov-html (0.12.3)
     simplecov_json_formatter (0.1.4)
-    stringio (3.0.8)
+    stringio (3.1.0)
     thor (1.2.2)
     timecop (0.9.6)
     unicode-display_width (2.4.2)

data/README.md

@@ -6,13 +6,19 @@
 <meta name="keywords" content="Control Plane, Heroku, Kubernetes, K8, Infrastructure">
 <meta name="google-site-verification" content="dIV4nMplcYl6YOKOaZMqgvdKXhLJ4cdYY6pS6e_YrPU" />
 
-_A gem that provides **Heroku Flow** functionality on Control Plane, including docs for migrating from [Heroku](https://heroku.com) to [Control Plane](https://controlplane.com)_
+_A gem that provides **Heroku Flow** functionality on Control Plane, including docs for migrating from [Heroku](https://heroku.com) to [Control Plane](https://shakacode.controlplane.com/)._
 
 [![RSpec](https://github.com/shakacode/heroku-to-control-plane/actions/workflows/rspec.yml/badge.svg)](https://github.com/shakacode/heroku-to-control-plane/actions/workflows/rspec.yml)
 [![Rubocop](https://github.com/shakacode/heroku-to-control-plane/actions/workflows/rubocop.yml/badge.svg)](https://github.com/shakacode/heroku-to-control-plane/actions/workflows/rubocop.yml)
 
 [![Gem](https://badge.fury.io/rb/cpl.svg)](https://badge.fury.io/rb/cpl)
 
+---
+
+_If you need a free demo account for Control Plane (no CC required), you can contact [controlplane@shakacode.com](mailto:controlplane@shakacode.com)._
+
+---
+
 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.
 
@@ -29,17 +35,18 @@ a **helper CLI** based on templates to save lots of day-to-day typing (and human
 2. [Concept Mapping](#concept-mapping)
 3. [Installation](#installation)
 4. [Steps to Migrate](#steps-to-migrate)
-5. [Config](#config)
-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)
-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)
-15. [Tips](/docs/tips.md)
+5. [Configuration Files](#configuration-files)
+6. [Workflow](#workflow)
+7. [Environment](#environment)
+8. [Database](#database)
+9. [In-memory Databases](#in-memory-databases)
+10. [Scheduled Jobs](#scheduled-jobs)
+11. [CLI Commands Reference](#cli-commands-reference)
+12. [Mapping of Heroku Commands to `cpl` and `cpln`](#mapping-of-heroku-commands-to-cpl-and-cpln)
+13. [Examples](#examples)
+14. [Migrating Postgres Database from Heroku Infrastructure](/docs/postgres.md)
+15. [Migrating Redis Database from Heroku Infrastructure](/docs/redis.md)
+16. [Tips](/docs/tips.md)
 
 ## Key Features
 
@@ -89,23 +96,30 @@ For the typical Rails app, this means:
 
 ## Installation
 
-1. Ensure your [Control Plane](https://controlplane.com) account is set up. Set up an `organization` <your-org> for testing in that account and modify value for `aliases.common.cpln_org` in `.controlplane/controlplane.yml`. If you need an organization, please [contact Shakcode](mailto:controlplane@shkacode.com).
-1. Install [Node.js](https://nodejs.org/en) (required for Control Plane CLI).
+1. Ensure your [Control Plane](https://shakacode.controlplane.com/) account is set up. Set up an `organization` `<your-org>` for testing in that account and modify the value for `aliases.common.cpln_org` in `.controlplane/controlplane.yml`, or you can also set it with the `CPLN_ORG` environment variable. If you need an organization, please [contact Shakacode](mailto:controlplane@shakacode.com).
+
+2. Install [Node.js](https://nodejs.org/en) (required for Control Plane CLI).
+
+3. Install [Ruby](https://www.ruby-lang.org/en/) (required for these helpers).
 
-1. Install [Ruby](https://www.ruby-lang.org/en/) (required for these helpers).
+4. Install Control Plane CLI, and configure access ([docs here](https://docs.controlplane.com/quickstart/quick-start-3-cli#getting-started-with-the-cli)).
 
-1. Install Control Plane CLI (and configure access) [docs here](https://docs.controlplane.com/quickstart/quick-start-3-cli#getting-started-with-the-cli), `npm install -g @controlplane/cli`. You can update the `cpln` command line with `npm update -g @controlplane/cli`. Then run `cpln login` to ensure access.
 ```sh
+# Install CLI
 npm install -g @controlplane/cli
+
+# Configure access
 cpln login
+
+# Update CLI
+npm update -g @controlplane/cli
 ```
 
-1. Run `cpln image docker-login --org <your-org>` to ensure that you have access to the Control Plane Docker registry.
+5. Run `cpln image docker-login --org <your-org>` to ensure that you have access to the Control Plane Docker registry.
 
-1. 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). You may also install `cpl` in your project's Gemfile.
+6. Install Heroku to Control Plane `cpl` CLI as a [Ruby gem](https://rubygems.org/gems/cpl): `gem install cpl`. If you want to hack on the source code, see [CONTRIBUTING.md](CONTRIBUTING.md). 
 
-1. This project has a `Dockerfile` for Control Plane in this directory. You can use it as an example for your project. Ensure that you have Docker running.
+7. You can use [this Dockerfile](https://github.com/shakacode/react-webpack-rails-tutorial/blob/master/.controlplane/Dockerfile) as an example for your project. Ensure that you have Docker running.
 
 **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.
@@ -116,7 +130,7 @@ Click [here](/docs/migrating.md) to see the steps to migrate.
 
 ## Configuration Files
 
-The `cpl` gem is based on several configuration files within a `/.controlplane` top-level directory in your Rails project.
+The `cpl` gem is based on several configuration files within a `/.controlplane` top-level directory in your project.
 
 ```
 .controlplane/
@@ -129,32 +143,46 @@ The `cpl` gem is based on several configuration files within a `/.controlplane`
 ├─ entrypoint.sh
 ```
 
-1. `controlplane.yml` describes the overall application. Be sure to have <your-org> as the value for `aliases.common.cpln_org`.
+1. `controlplane.yml` describes the overall application. Be sure to have `<your-org>` as the value for `aliases.common.cpln_org`, or set it with the `CPLN_ORG` environment variable.
 2. `Dockerfile` builds the production application. `entrypoint.sh` is an _example_ entrypoint script for the production application, referenced in your Dockerfile.
 3. `templates` directory contains the templates for the various workloads, such as `rails.yml` and `postgres.yml`.
-4. `templates/gvc.yml` defines your project's GVC (like a Heroku app). Most importantly, it contains ENV values for app.
-5. `templates/rails.yml` defines your Rails workload. It may inherit ENV values from the parent GVC, which is populated from the `templates/gvc.yml`. This file also configures scaling, sizing, firewalls, and other workload specific values.
-6. For other workloads (like lines in a Heroku Procfile), you create additional template files. For example, you can base a `templates/sidekiq.yml` on the `templates/rails.yml` file.
-7. You can have other files in the `templates` directory, such as `redis.yml` and `postgres.yml` which could setup Redis and Postgres for a testing application.
+4. `templates/gvc.yml` defines your project's GVC (like a Heroku app). More importantly, it contains ENV values for the app.
+5. `templates/rails.yml` defines your Rails workload. It may inherit ENV values from the parent GVC, which is populated from the `templates/gvc.yml`. This file also configures scaling, sizing, firewalls, and other workload-specific values.
+6. For other workloads (like lines in a Heroku `Procfile`), you create additional template files. For example, you can base a `templates/sidekiq.yml` on the `templates/rails.yml` file.
+7. You can have other files in the `templates` directory, such as `redis.yml` and `postgres.yml`, which could setup Redis and Postgres for a testing application.
 
 Here's a complete example of all supported config keys explained for the `controlplane.yml` file:
-                                                       
+
 ### `controlplane.yml`
+
 ```yaml
 # Keys beginning with "cpln_" correspond to your settings in Control Plane.
 
+# Global settings that apply to `cpl` usage.
+# You can opt out of allowing the use of CPLN_ORG and CPLN_APP env vars
+# to avoid any accidents with the wrong org / app.
+allow_org_override_by_env: true
+allow_app_override_by_env: true
+
 aliases:
   common: &common
-    # Organization name for staging (customize to your needs).
-    # Production apps will use a different organization, specified below, for security.
+    # Organization for staging and QA apps is typically set as an alias.
+    # Production apps will use a different organization, specified in `apps`, for security.
+    # Change this value to your organization name
+    # or set the CPLN_ORG env var and it will override this for all `cpl` commands
+    # (provided that `allow_org_override_by_env` is set to `true`).
     cpln_org: my-org-staging
 
-    # Example apps use only one location. Control Plane offers the ability to use multiple locations.
+    # Control Plane offers the ability to use multiple locations.
+    # default_location is used for commands that require a location
+    # including `ps`, `run`, `run:detached`, `apply-template`.
+    # This can be overridden with option --location=<location> and
+    # CPLN_LOCATION environment variable.
     default_location: aws-us-east-2
 
     # Allows running the command `cpl setup-app`
     # instead of `cpl apply-template gvc redis postgres memcached rails sidekiq`.
-    setup:
+    setup_app_templates:
       - gvc
       - redis
       - postgres
@@ -214,6 +242,11 @@ apps:
   my-app-production:
     <<: *common
 
+    # You can also opt out of allowing the use of CPLN_ORG and CPLN_APP env vars per app.
+    # It's recommended to leave this off for production, to avoid any accidents.
+    allow_org_override_by_env: false
+    allow_app_override_by_env: false
+
     # Use a different organization for production.
     cpln_org: my-org-production
 
@@ -234,58 +267,64 @@ apps:
 
 ## Workflow
 
-For a live example, see the [react-webpack-rails-tutorial](https://github.com/shakacode/react-webpack-rails-tutorial/blob/master/.controlplane/readme.md).
+For a live example, see the [react-webpack-rails-tutorial](https://github.com/shakacode/react-webpack-rails-tutorial/blob/master/.controlplane/readme.md) repository.
+
 This example should closely match the below example.
 
 Suppose your app is called `tutorial-app`. You can run the following commands.
 
 ### Setup Commands
+
 ```sh
 # Provision all infrastructure on Control Plane.
-# app tutorial-app will be created per definition in .controlplane/controlplane.yml
-cpl apply-template gvc postgres redis rails -a tutorial-app
+# `tutorial-app` will be created per definition in .controlplane/controlplane.yml.
+cpl apply-template gvc postgres redis rails daily-task -a tutorial-app
 
-# Build and push docker image to Control Plane repository
-# Note, may take many minutes. Be patient. Check for error messages, such as forgetting to run `cpln image docker-login --org <your-org>`
+# Build and push the Docker image to the Control Plane repository.
+# Note, it may take many minutes. Be patient.
+# Check for error messages, such as forgetting to run `cpln image docker-login --org <your-org>`.
 cpl build-image -a tutorial-app
 
-# Promote image to app after running `cpl build-image command`
-# Note, the UX of images may not show the image for up to 5 minutes. However, it's ready.
+# Promote the image to the app after running the `cpl build-image` command.
+# Note, the UX of the images may not show the image for up to 5 minutes. However, it's ready.
 cpl deploy-image -a tutorial-app
 
-# See how app is starting up
+# See how the app is starting up.
 cpl logs -a tutorial-app
 
-# Open app in browser (once it has started up)
+# Open the app in browser (once it has started up).
 cpl open -a tutorial-app
 ```
 
-### Promoting code updates
+### Promoting Code Updates
 
 After committing code, you will update your deployment of `tutorial-app` with the following commands:
 
 ```sh
-# Build and push new image with sequential image tagging, e.g. 'tutorial-app:1', then 'tutorial-app:2', etc.
+# Build and push a new image with sequential image tagging, e.g. 'tutorial-app:1', then 'tutorial-app:2', etc.
 cpl build-image -a tutorial-app
 
-# 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 the latest image,
+# while the app is still running on the previous image.
 # This is analogous to the release phase.
-cpl runner rails db:migrate -a tutorial-app --image latest
+cpl run:detached rails db:migrate -a tutorial-app --image latest
 
-# Pomote latest image to app
+# Pomote the latest image to the app.
 cpl deploy-image -a tutorial-app
 ```
 
 If you needed to push a new image with a specific commit SHA, you can run the following command:
 
 ```sh
-# Build and push with sequential image tagging and commit SHA, e.g. 'tutorial-app:123_ABCD'
+# Build and push with sequential image tagging and commit SHA, e.g. 'tutorial-app:123_ABCD', etc.
 cpl build-image -a tutorial-app --commit ABCD
 ```
 
 ### Real World
-Most companies will configure their CI system to handle the above steps. Please [contact Shakcode](mailto:controlplane@shkacode.com) for examples of how to do this, jump on [**React+Rails Slack channel**] (https://reactrails.slack.com/join/shared_invite/enQtNjY3NTczMjczNzYxLTlmYjdiZmY3MTVlMzU2YWE0OWM0MzNiZDI0MzdkZGFiZTFkYTFkOGVjODBmOWEyYWQ3MzA2NGE1YWJjNmVlMGE).
+
+Most companies will configure their CI system to handle the above steps. Please [contact Shakacode](mailto:controlplane@shakacode.com) for examples of how to do this.
+
+You can also join our [**Slack channel**](https://reactrails.slack.com/join/shared_invite/enQtNjY3NTczMjczNzYxLTlmYjdiZmY3MTVlMzU2YWE0OWM0MzNiZDI0MzdkZGFiZTFkYTFkOGVjODBmOWEyYWQ3MzA2NGE1YWJjNmVlMGE) for ShakaCode open source projects.
 
 ## Environment
 
@@ -307,25 +346,27 @@ It is also possible to set up a Secret store (of type `Dictionary`), which we ca
 Policy to access the secret.
 
 In `templates/gvc.yml`:
+
 ```yaml
 spec:
   env:
     - name: MY_GLOBAL_VAR
-      value: 'value'
+      value: "value"
     - name: MY_SECRET_GLOBAL_VAR
-      value: 'cpln://secret/MY_SECRET_STORE_NAME/MY_SECRET_GLOBAL_VAR'
+      value: "cpln://secret/MY_SECRET_STORE_NAME/MY_SECRET_GLOBAL_VAR"
 ```
 
 In `templates/rails.yml`:
+
 ```yaml
 spec:
   containers:
     - name: rails
       env:
         - name: MY_LOCAL_VAR
-          value: 'value'
+          value: "value"
         - name: MY_SECRET_LOCAL_VAR
-          value: 'cpln://secret/MY_SECRET_STORE_NAME/MY_SECRET_LOCAL_VAR'
+          value: "cpln://secret/MY_SECRET_STORE_NAME/MY_SECRET_LOCAL_VAR"
       inheritEnv: true # To enable global env inheritance.
 ```
 
@@ -387,7 +428,7 @@ spec:
   type: cron
   job:
     # Run daily job at 2am.
-    schedule: 0  2  *  *  *
+    schedule: "0 2 * * *"
     # "Never" or "OnFailure"
     restartPolicy: Never
   containers:

data/docs/commands.md

@@ -100,7 +100,7 @@ cpl copy-image-from-upstream -a $APP_NAME --upstream-token $UPSTREAM_TOKEN --ima
 
 ### `delete`
 
-- Deletes the whole app (GVC with all workloads and all images)
+- Deletes the whole app (GVC with all workloads, all volumesets and all images)
 - Will ask for explicit user confirmation
 
 ```sh
@@ -131,6 +131,15 @@ cpl env -a $APP_NAME
 if [ cpl exists -a $APP_NAME ]; ...
 ```
 
+### `generate`
+
+Creates base Control Plane config and template files
+
+```sh
+# Creates .controlplane directory with Control Plane config and other templates
+cpl generate
+```
+
 ### `info`
 
 - Displays the diff between defined/available apps/workloads (apps equal GVCs)
@@ -140,7 +149,7 @@ if [ cpl exists -a $APP_NAME ]; ...
 - The diff is based on what's defined in the `.controlplane/controlplane.yml` file
 
 ```sh
-# Shows diff for all apps in all orgs.
+# Shows diff for all apps in all orgs (based on `.controlplane/controlplane.yml`).
 cpl info
 
 # Shows diff for all apps in a specific org.
@@ -227,6 +236,15 @@ cpl open -a $APP_NAME
 cpl open -a $APP_NAME -w $WORKLOAD_NAME
 ```
 
+### `open-console`
+
+- Opens the app console on Control Plane in the default browser
+- Can also go directly to a workload page if `--workload` is provided
+
+```sh
+cpl open-console -a $APP_NAME
+```
+
 ### `promote-app-from-upstream`
 
 - Copies the latest image from upstream, runs a release script (optional), and deploys the image
@@ -303,7 +321,6 @@ cpl ps:swait -a $APP_NAME -w $WORKLOAD_NAME
 
 - Runs one-off **_interactive_** replicas (analog of `heroku run`)
 - Uses `Standard` workload type and `cpln exec` as the execution method, with CLI streaming
-- May not work correctly with tasks that last over 5 minutes (there's a Control Plane scaling bug at the moment)
 - If `fix_terminal_size` is `true` in the `.controlplane/controlplane.yml` file, the remote terminal size will be fixed to match the local terminal size (may also be overriden through `--terminal-size`)
 
 > **IMPORTANT:** Useful for development where it's needed for interaction, and where network connection drops and
@@ -382,8 +399,8 @@ cpl run:detached rails db:migrate:status -a $APP_NAME --use-local-token
 ### `setup-app`
 
 - Creates an app and all its workloads
-- Specify the templates for the app and workloads through `setup` in the `.controlplane/controlplane.yml` file
-- This should should only be used for temporary apps like review apps, never for persistent apps like production (to update workloads for those, use 'cpl apply-template' instead)
+- Specify the templates for the app and workloads through `setup_app_templates` in the `.controlplane/controlplane.yml` file
+- This should only be used for temporary apps like review apps, never for persistent apps like production (to update workloads for those, use 'cpl apply-template' instead)
 
 ```sh
 cpl setup-app -a $APP_NAME

data/docs/migrating.md

@@ -29,13 +29,13 @@ Edit the `.controlplane/controlplane.yml` file as needed. Note that the `my-app-
 is defined in this file. See
 [this example](https://github.com/shakacode/react-webpack-rails-tutorial/blob/master/.controlplane/controlplane.yml).
 
-Before the initial setup, add the templates for the app to the `.controlplane/controlplane.yml` file, using the `setup`
+Before the initial setup, add the templates for the app to the `.controlplane/controlplane.yml` file, using the `setup_app_templates`
 key, e.g.:
 
 ```yaml
 my-app-staging:
   <<: *common
-  setup:
+  setup_app_templates:
     - gvc
     - redis
     - memcached
@@ -191,7 +191,7 @@ configure an entry for, e.g., `my-app-review`, and then create review apps start
   my-app-review:
     <<: *common
     match_if_app_name_starts_with: true
-    setup:
+    setup_app_templates:
       - gvc
       - redis
       - memcached

data/examples/controlplane.yml

@@ -1,15 +1,38 @@
 # Keys beginning with "cpln_" correspond to your settings in Control Plane.
 
+# Global settings that apply to `cpl` usage.
+# You can opt out of allowing the use of CPLN_ORG and CPLN_APP env vars
+# to avoid any accidents with the wrong org / app.
+allow_org_override_by_env: true
+allow_app_override_by_env: true
+
 aliases:
   common: &common
-    # Organization name for staging (customize to your needs).
-    # Production apps will use a different organization, specified below, for security.
+    # Organization for staging and QA apps is typically set as an alias.
+    # Production apps will use a different organization, specified in `apps`, for security.
+    # Change this value to your organization name
+    # or set the CPLN_ORG env var and it will override this for all `cpl` commands
+    # (provided that `allow_org_override_by_env` is set to `true`).
     cpln_org: my-org-staging
 
-    # Example apps use only one location. Control Plane offers the ability to use multiple locations.
+    # Control Plane offers the ability to use multiple locations.
+    # default_location is used for commands that require a location
+    # including `ps`, `run`, `run:detached`, `apply-template`.
+    # This can be overridden with option --location=<location> and
+    # CPLN_LOCATION environment variable.
     # TODO: Allow specification of multiple locations.
     default_location: aws-us-east-2
 
+    # Allows running the command `cpl setup-app`
+    # instead of `cpl apply-template gvc redis postgres memcached rails sidekiq`.
+    setup:
+      - gvc
+      - redis
+      - postgres
+      - memcached
+      - rails
+      - sidekiq
+
     # Configure the workload name used as a template for one-off scripts, like a Heroku one-off dyno.
     one_off_workload: rails
 
@@ -24,26 +47,62 @@ aliases:
       - 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
 
+    # Fixes the remote terminal size to match the local terminal size
+    # when running the commands `cpl run` or `cpl run:detached`.
+    fix_terminal_size: true
+
+    # Apps with a deployed image created before this amount of days will be listed for deletion
+    # when running the command `cpl cleanup-stale-apps`.
+    stale_app_image_deployed_days: 5
+
+    # Images that exceed this quantity will be listed for deletion
+    # when running the command `cpl cleanup-images`.
+    image_retention_max_qty: 20
+
+    # Images created before this amount of days will be listed for deletion
+    # when running the command `cpl cleanup-images` (`image_retention_max_qty` takes precedence).
+    image_retention_days: 5
+
+    # Run workloads created before this amount of days will be listed for deletion
+    # when running the command `cpl run:cleanup`.
+    stale_run_workload_created_days: 2
+
 apps:
   my-app-staging:
     # Use the values from the common section above.
     <<: *common
+
   my-app-review:
     <<: *common
+
     # 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
+
+    # You can also opt out of allowing the use of CPLN_ORG and CPLN_APP env vars per app.
+    # It's recommended to leave this off for production, to avoid any accidents.
+    allow_org_override_by_env: false
+    allow_app_override_by_env: false
+
     # 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.
     upstream: my-app-staging
+
+    # Used by the command `cpl promote-app-from-upstream` to run a release script before deploying.
+    # This is relative to the `.controlplane/` directory.
+    release_script: release_script
+
   my-app-other:
     <<: *common
+
     # You can specify a different `Dockerfile` relative to the `.controlplane/` directory (defaults to "Dockerfile").
     dockerfile: ../some_other/Dockerfile