Doc Updates

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 promote-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 promote-image -a tutorial-app
 ```
 
 ## Other notes

Gemfile

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

Gemfile.lock

@@ -89,6 +89,7 @@ GEM
     capybara-screenshot (1.0.26)
       capybara (>= 1.0, < 4)
       launchy
+    cgi (0.3.6)
     code_analyzer (0.5.5)
       sexp_processor
     coderay (1.1.3)
@@ -106,6 +107,17 @@ GEM
       term-ansicolor (~> 1.6)
       thor (>= 0.20.3, < 2.0)
       tins (~> 1.16)
+    cpl (0.1.0)
+      cgi (~> 0.3.6)
+      debug (~> 1.7.1)
+      dotenv (~> 2.8.1)
+      json (~> 2.6.3)
+      net-http (~> 0.3.2)
+      pathname (~> 0.2.1)
+      psych (~> 5.1.0)
+      tempfile (~> 0.1.3)
+      thor (~> 1.2.1)
+      yaml (~> 0.2.1)
     crass (1.0.6)
     database_cleaner (2.0.1)
       database_cleaner-active_record (~> 2.0.0)
@@ -120,6 +132,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)
@@ -164,6 +177,8 @@ GEM
     mini_mime (1.1.2)
     mini_portile2 (2.8.1)
     minitest (5.17.0)
+    net-http (0.3.2)
+      uri
     net-imap (0.3.4)
       date
       net-protocol
@@ -180,6 +195,7 @@ GEM
     parallel (1.22.1)
     parser (3.2.0.0)
       ast (~> 2.4.1)
+    pathname (0.2.1)
     pg (1.4.5)
     pry (0.14.2)
       coderay (~> 1.1)
@@ -198,7 +214,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 +334,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)
@@ -349,6 +365,7 @@ GEM
       sprockets (>= 3.0.0)
     stringio (3.0.4)
     sync (0.5.0)
+    tempfile (0.1.3)
     term-ansicolor (1.7.1)
       tins (~> 1.0)
     thor (1.2.1)
@@ -361,6 +378,7 @@ GEM
     uglifier (4.2.0)
       execjs (>= 0.3.0, < 3)
     unicode-display_width (2.4.2)
+    uri (0.12.0)
     web-console (4.2.0)
       actionview (>= 6.0.0)
       activemodel (>= 6.0.0)
@@ -377,6 +395,7 @@ GEM
     websocket-extensions (0.1.5)
     xpath (3.2.0)
       nokogiri (~> 1.8)
+    yaml (0.2.1)
     yard (0.9.28)
       webrick (~> 1.7.0)
     zeitwerk (2.6.6)
@@ -391,6 +410,7 @@ DEPENDENCIES
   capybara-screenshot
   coffee-rails
   coveralls_reborn (~> 0.25.0)
+  cpl
   database_cleaner
   debug (>= 1.0.0)
   factory_bot_rails