README.md in cpl-0.1.0 vs README.md in cpl-0.2.0

- old
+ new

@@ -1,9 +1,14 @@ -# Heroku to Control Plane +# Heroku to Control Plane `cpl` CLI _A playbook for migrating from [Heroku](https://heroku.com) to [Control Plane](https://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) + 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. Control Plane, on the other hand, gives you access to raw cloud computing power. However, you need to know precisely how to use it. @@ -18,12 +23,12 @@ 7. [Database](#database) 8. [In-memory databases](#in-memory-databases) 9. [CLI commands reference](#cli-commands-reference) 10. [Mapping of Heroku Commands to `cpl` and `cpln`](#mapping-of-heroku-commands-to-cpl-and-cpln) 11. [Examples](#examples) -12. [Migrating Postgres database from Heroku infrastructure](/postgres.md) -13. [Migrating Redis database from Heroku infrastructure](/redis.md) +12. [Migrating Postgres database from Heroku infrastructure](/docs/postgres.md) +13. [Migrating Redis database from Heroku infrastructure](/docs/redis.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. - Easy to understand Heroku to Control Plane conventions in setup and naming. @@ -67,30 +72,25 @@ | in-memory db | `redis`, `memcached` | add-on | external provider or can be set up for development/testing with Docker image (lacks persistence between restarts) | | special something | `mailtrap` | add-on | external provider or can be set up for development/testing with Docker image (lacks persistence between restarts) | ## Installation -**Note:** `cpl` CLI is configured via a local clone clone of this repo. We may publish it later as a Ruby gem or Node package. +**Note:** `cpl` CLI is configured either a Ruby gem, [`cpl`](https://rubygems.org/gems/cpl) install or a local clone clone. For information on the latter, see [CONTRIBUTING.md](CONTRIBUTING.md). 1. Install `node` (required for Control Plane CLI). 2. Install `ruby` (required for these helpers). -3. Install Control Plane CLI (adds `cpln` command) and configure credentials. +3. Install Control Plane CLI (adds `cpln` command) and configure credentials by running command `cpln login`. ```sh npm install -g @controlplane/cli cpln login ``` -4. Install this repo locally and alias `cpl` command globally for easier access, e.g.: +## 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. -```sh -git clone https://github.com/shakacode/heroku-to-control-plane -# Create an alias in some local shell startup script, e.g., `.profile`, `.bashrc`, etc. -alias cpl="~/projects/heroku-to-control-plane/cpl" -``` - - For each Git project that you want to deploy to Control Plane, copy project-specific configs to a `.controlplane` directory at the top of your project. `cpl` will pick those up depending on which project folder tree it runs. Thus, this automates running several projects with different configs without explicitly switching configs. 5. Create a `Dockerfile` for your production deployment. See [this example](https://github.com/shakacode/react-webpack-rails-tutorial/blob/master/.controlplane/Dockerfile). @@ -99,10 +99,12 @@ **Notes:** 1. `myapp` is an app name defined in the `.controlplane/controlplane.yml` file, such as `ror-tutorial` in [this `controlplane.yml` file](https://github.com/shakacode/react-webpack-rails-tutorial/blob/master/.controlplane/controlplane.yml). 2. Other files in the `.controlplane/templates` directory are used by the `cpl setup` command. +### Initial Setup and Deployment + ```sh # Provision infrastructure (one-time-only for new apps) using templates. # Note how the arguments correspond to files in the `.controlplane/templates` directory. cpl setup gvc postgres redis memcached rails sidekiq -a myapp @@ -117,10 +119,30 @@ # Open app in browser. cpl open -a myapp ``` +### Promoting code upgrades + +```sh +# Build and push new image with sequential image tagging, e.g. 'ror-tutorial_123' +cpl build-image -a ror-tutorial + +# OR +# Build and push with sequential image tagging and commit SHA, e.g. 'ror-tutorial_123_ABCD' +cpl build-image -a ror-tutorial --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 + +# Pomote latest image to app +cpl promote-image -a ror-tutorial +``` + + ## Example project modifications for Control Plane _See this for a complete example._ To learn how to migrate an app, we recommend that you first follow along with [this example project](https://github.com/shakacode/react-webpack-rails-tutorial). @@ -298,20 +320,20 @@ ## Mapping of Heroku Commands to `cpl` and `cpln` **`[WIP]`** -| Heroku Command | `cpl` or `cpln` | -| ---------------------------------------------------------------------------------------------------------------- | --------------- | -| `[heroku ps](https://devcenter.heroku.com/articles/heroku-cli-commands#heroku-ps-type-type)` | `cpl ps` | -| `[heroku config](https://devcenter.heroku.com/articles/heroku-cli-commands#heroku-config)` | ? | -| `[heroku maintenance](https://devcenter.heroku.com/articles/heroku-cli-commands#heroku-maintenance)` | ? | -| `[heroku logs](https://devcenter.heroku.com/articles/heroku-cli-commands#heroku-logs)` | `cpl logs` | -| `[heroku pg](https://devcenter.heroku.com/articles/heroku-cli-commands#heroku-pg-database)` | ? | -| `[heroku pipelines:promote](https://devcenter.heroku.com/articles/heroku-cli-commands#heroku-pipelines-promote)` | `cpl promote` | -| `[heroku psql](https://devcenter.heroku.com/articles/heroku-cli-commands#heroku-psql-database)` | ? | -| `[heroku redis](https://devcenter.heroku.com/articles/heroku-cli-commands#heroku-redis-database)` | ? | -| `[heroku releases](https://devcenter.heroku.com/articles/heroku-cli-commands#heroku-releases)` | ? | +| Heroku Command | `cpl` or `cpln` | +| -------------------------------------------------------------------------------------------------------------- | --------------- | +| [heroku ps](https://devcenter.heroku.com/articles/heroku-cli-commands#heroku-ps-type-type) | `cpl ps` | +| [heroku config](https://devcenter.heroku.com/articles/heroku-cli-commands#heroku-config) | ? | +| [heroku maintenance](https://devcenter.heroku.com/articles/heroku-cli-commands#heroku-maintenance) | ? | +| [heroku logs](https://devcenter.heroku.com/articles/heroku-cli-commands#heroku-logs) | `cpl logs` | +| [heroku pg](https://devcenter.heroku.com/articles/heroku-cli-commands#heroku-pg-database) | ? | +| [heroku pipelines:promote](https://devcenter.heroku.com/articles/heroku-cli-commands#heroku-pipelines-promote) | `cpl promote` | +| [heroku psql](https://devcenter.heroku.com/articles/heroku-cli-commands#heroku-psql-database) | ? | +| [heroku redis](https://devcenter.heroku.com/articles/heroku-cli-commands#heroku-redis-database) | ? | +| [heroku releases](https://devcenter.heroku.com/articles/heroku-cli-commands#heroku-releases) | ? | ## Examples 1. See `examples/` and `templates/` folders of this repo. 2. See `.controlplane` directory of this live example: [react-webpack-rails-tutorial](https://github.com/shakacode/react-webpack-rails-tutorial/tree/master/.controlplane)