Doc Updates for Control Plane (#521)

Author: justin808

.controlplane/controlplane.yml

@@ -3,10 +3,10 @@ aliases:
   common: &common
     # Change this to your org name for staging. Production apps will use a different org
     # for security.
-    org: shakacode-staging
+    cpln_org: shakacode-demo
     # Change `shakacode-staging` to your-org-name-for-staging
     # Example apps use only location. CPLN offers the ability to use multiple locations.
-    location: aws-us-east-2
+    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
     # Like the entries in the Heroku Procfile that get deployed when the application code changes
@@ -19,10 +19,13 @@ aliases:
       - postgres
 
 apps:
-  ror-tutorial:
-    <<: *common
   react-webpack-rails-tutorial:
     <<: *common
-  ror-tutorial-review:
+  tutorial-app:
+    <<: *common
+  # QA Apps are like Heroku review apps, but the use `prefix` so you can run a commmand like
+  # this to create a QA app for the tutorial app.
+  # `cpl setup gvc postgres redis rails -a qa-tutorial-app-pr-1234`
+  qa-tutorial-app:
     <<: *common
     prefix: true

.controlplane/readme.md

@@ -1,58 +1,78 @@
 # Deploying tutorial app on Control Plane
 
+## Overview
+This simple example shows how to deploy a simple app on Control Plane using the `cpl` gem.
+
+To maximize simplicity, this example creates Postgres and Redis as workloads in the same GVC as the app.
+In a real app, you would likely use persistent, external resources, such as AWS RDS and AWS ElastiCache.
+
+You can see the definition of Postgres and Redis in the `.controlplane/templates` directory.
+
 ## Prerequisites
 
-1. Should have [Control Plane](https://controlplane.com) account set up.
+1. Ensure your [Control Plane](https://controlplane.com) account is set up.
+
+2. Set up an `organization` for testing in that account and modify `aliases.common.cpln_org` in `.controlplane/controlplane.yml` .
+
+3. Install Control Plane CLI (and configure access) [docs here](https://docs.controlplane.com/quickstart/quick-start-3-cli#getting-started-with-the-cli). You can update the `cpln` command line with the same command as installation, `npm install -g @controlplane/cli`. Then run `cpln login` to ensure access.
+
+4. Install [Heroku to Control Plane](https://github.com/shakacode/heroku-to-control-plane) playbook CLI [`cpl` gem](https://rubygems.org/gems/cpl) on your project's Gemfile or globally.
 
-2. Set up `organization` for testing in that account and modify org `.controlplane/controlplane.yml` .
+5. 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.
 
-3. Install Control Plane CLI (and configure access) [docs here](https://docs.controlplane.com/quickstart/quick-start-3-cli#getting-started-with-the-cli).
+## Tips
+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.
 
-4. Install Heroku to Control Plane playbook from https://github.com/shakacode/heroku-to-control-plane.
+## Project Configuration
+See the filese in the `./controlplane` directory.
 
-5. This project has a `Dockerfile` for Control Plane in this directory. You can use it as an example for your project.
+1. `/templates`: defines the objects created with the `cpl setup` command.
+2. `/controlplane.yml`: defines the organization, location, and app name.
+3. `Dockerfile`: defines the Docker image used to run the app on Control Plane.
+4. `entrypoint.sh`: defines the entrypoint script used to run the app on Control Plane.
 
 ## Setup and run
 
-Check if the organization and location are correct in `.controlplane/controlplane.yml`.
+Check if the Control Plane organization and location are correct in `.controlplane/controlplane.yml`. You should be able to see this information in the Control Plane UI.
 
 ```sh
 # Note, below commands use `cpl` which is the Heroku to Control Plane playbook script.
 
-# Provision all infrastructure on Control Plane. It will use templates from .controlplane/templates folder.
-cpl setup gvc postgres redis rails -a ror-tutorial
+# Provision all infrastructure on Control Plane.
+# app tutorial-app will be created per definition in .controlplane/controlplane.yml
+cpl setup gvc postgres redis rails -a tutorial-app
 
 # Build and push docker image to Control Plane repository
 # Note, may take many minutes. Be patient.
-cpl build -a ror-tutorial
+cpl build-image -a tutorial-app
 
-# Promote image to app after running `cpl build command`
-cpl promote -a ror-tutorial
+# Promote image to app after running `cpl build-image command`
+cpl deploy-image -a tutorial-app
 
 # See how app is starting up
-cpl logs -a ror-tutorial
+cpl logs -a tutorial-app
 
 # Open app in browser (once it has started up)
-cpl open -a ror-tutorial
+cpl open -a tutorial-app
 ```
 
 ## Promoting code upgrades
 
 ```sh
 # Build and push new image with sequential image tagging, e.g. 'ror-tutorial_123'
-cpl build -a ror-tutorial
+cpl build-image -a tutorial-app
 
 # OR
 # Build and push with sequential image tagging and commit SHA, e.g. 'ror-tutorial_123_ABCD'
-cpl build -a ror-tutorial --commit ABCD
+cpl build-image -a tutorial-app --commit ABCD
 
 # 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 runner rails db:migrate -a ror-tutorial --image latest
+cpl runner rails db:migrate -a tutorial-app --image latest
 
 # Pomote latest image to app
-promote -a ror-tutorial
+cpl deploy-image -a tutorial-app
 ```
 
 ## Other notes

Gemfile

@@ -7,6 +7,7 @@ ruby "3.1.2"
 
 gem "react_on_rails", "13.2.0"
 gem "shakapacker", "6.5.5"
+gem "cpl", "~> 0.3.3"
 
 # Bundle edge Rails instead: gem "rails", github: "rails/rails"
 gem "listen"

Gemfile.lock

@@ -106,6 +106,11 @@ GEM
       term-ansicolor (~> 1.6)
       thor (>= 0.20.3, < 2.0)
       tins (~> 1.16)
+    cpl (0.3.3)
+      debug (~> 1.7.1)
+      dotenv (~> 2.8.1)
+      psych (~> 5.1.0)
+      thor (~> 1.2.1)
     crass (1.0.6)
     database_cleaner (2.0.1)
       database_cleaner-active_record (~> 2.0.0)
@@ -120,6 +125,7 @@ GEM
     debug_inspector (1.1.0)
     diff-lcs (1.5.0)
     docile (1.4.0)
+    dotenv (2.8.1)
     erubi (1.12.0)
     erubis (2.7.0)
     execjs (2.8.1)
@@ -198,7 +204,7 @@ GEM
     pry-stack_explorer (0.6.1)
       binding_of_caller (~> 1.0)
       pry (~> 0.13)
-    psych (5.0.2)
+    psych (5.1.0)
       stringio
     public_suffix (5.0.1)
     puma (6.0.2)
@@ -318,7 +324,7 @@ GEM
       tilt
     scss_lint (0.59.0)
       sass (~> 3.5, >= 3.5.5)
-    sdoc (2.6.0)
+    sdoc (2.6.1)
       rdoc (>= 5.0)
     selenium-webdriver (4.7.1)
       rexml (~> 3.2, >= 3.2.5)
@@ -391,6 +397,7 @@ DEPENDENCIES
   capybara-screenshot
   coffee-rails
   coveralls_reborn (~> 0.25.0)
+  cpl (~> 0.3.3)
   database_cleaner
   debug (>= 1.0.0)
   factory_bot_rails
@@ -436,4 +443,4 @@ RUBY VERSION
    ruby 3.1.2p20
 
 BUNDLED WITH
-   2.3.26
+   2.4.7