README.md in cpl-1.1.2 vs README.md in cpl-1.2.0

- old
+ new

@@ -4,17 +4,23 @@ <meta name="description" content="Instructions on how to migrate from Heroku to Control Plane and a CLI called cpl to make it easier."> <meta name="copyright" content="ShakaCode, 2023"> <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. 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. @@ -88,11 +94,11 @@ | 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 -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 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). +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). @@ -109,12 +115,11 @@ npm update -g @controlplane/cli ``` 5. Run `cpln image docker-login --org <your-org>` to ensure that you have access to the Control Plane Docker registry. -6. 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). 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. @@ -136,11 +141,11 @@ ├─ controlplane.yml ├─ Dockerfile ├─ entrypoint.sh ``` -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. +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). 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. @@ -151,22 +156,35 @@ ### `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 - memcached - rails @@ -222,10 +240,15 @@ 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. @@ -253,11 +276,11 @@ ### Setup Commands ```sh # Provision all infrastructure on Control Plane. # `tutorial-app` will be created per definition in .controlplane/controlplane.yml. -cpl apply-template gvc postgres redis rails -a tutorial-app +cpl apply-template gvc postgres redis rails daily-task -a tutorial-app # 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 @@ -403,10 +426,10 @@ name: daily-task spec: type: cron job: # Run daily job at 2am. - schedule: 0 2 * * * + schedule: "0 2 * * *" # "Never" or "OnFailure" restartPolicy: Never containers: - name: daily-task args: