README.md in cpl-1.1.2.rc.0 vs README.md in cpl-1.1.2

- old
+ new

@@ -27,21 +27,22 @@ 1. [Key Features](#key-features) 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 - 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. @@ -87,38 +88,46 @@ | 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 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://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. Install [Ruby](https://www.ruby-lang.org/en/) (required for these helpers). +2. Install [Node.js](https://nodejs.org/en) (required for Control Plane 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. +3. 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)). + ```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. +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. -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. ## Steps to Migrate 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/ ├─ templates/ │ ├─ gvc.yml @@ -127,21 +136,22 @@ ├─ 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`. +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. aliases: common: &common @@ -232,63 +242,69 @@ dockerfile: ../some_other/Dockerfile ``` ## 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 +# `tutorial-app` will be created per definition in .controlplane/controlplane.yml. cpl apply-template gvc postgres redis rails -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 There are two main places where we can set up environment variables in Control Plane: - **In `workload/container/env`** - those are container-specific and must be set up individually for each container. @@ -305,28 +321,30 @@ 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. 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. ``` ## Database