cpflow 3.0.0

data/docs/commands.md

@@ -0,0 +1,454 @@
+<!-- NOTE: This file is automatically generated by running `script/generate_commands_docs`. Do NOT edit it manually. -->
+
+## Common Options
+
+```
+-a XXX, --app XXX         app ref on Control Plane (GVC)
+```
+
+This `-a` option is used in most of the commands and will pick all other app configurations from the project-specific
+`.controlplane/controlplane.yml` file.
+
+## Commands
+
+### `apply-template`
+
+- Applies application-specific configs from templates (e.g., for every review-app)
+- Publishes (creates or updates) those at Control Plane infrastructure
+- Picks templates from the `.controlplane/templates` directory
+- Templates are ordinary Control Plane templates but with variable preprocessing
+
+**Preprocessed template variables:**
+
+```
+{{APP_ORG}}           - organization name
+{{APP_NAME}}          - GVC/app name
+{{APP_LOCATION}}      - location, per YML file, ENV, or command line arg
+{{APP_LOCATION_LINK}} - full link for location, ready to be used for the value of `staticPlacement.locationLinks` in the templates
+{{APP_IMAGE}}         - latest app image
+{{APP_IMAGE_LINK}}    - full link for latest app image, ready to be used for the value of `containers[].image` in the templates
+{{APP_IDENTITY}}      - default identity
+{{APP_IDENTITY_LINK}} - full link for identity, ready to be used for the value of `identityLink` in the templates
+```
+
+```sh
+# Applies single template.
+cpflow apply-template redis -a $APP_NAME
+
+# Applies several templates (practically creating full app).
+cpflow apply-template app postgres redis rails -a $APP_NAME
+```
+
+### `build-image`
+
+- Builds and pushes the image to Control Plane
+- Automatically assigns image numbers, e.g., `app:1`, `app:2`, etc.
+- Uses `.controlplane/Dockerfile` or a different Dockerfile specified through `dockerfile` in the `.controlplane/controlplane.yml` file
+- If a commit is provided through `--commit` or `-c`, it will be set as the runtime env var `GIT_COMMIT`
+- Accepts extra options that are passed to `docker build`
+
+```sh
+cpflow build-image -a $APP_NAME
+```
+
+### `cleanup-images`
+
+- Deletes all images for an app that either exceed the max quantity or are older than the specified amount of days
+- Specify the max quantity through `image_retention_max_qty` in the `.controlplane/controlplane.yml` file
+- Specify the amount of days through `image_retention_days` in the `.controlplane/controlplane.yml` file
+- If `image_retention_max_qty` is specified, any images that exceed it will be deleted, regardless of `image_retention_days`
+- Will ask for explicit user confirmation
+- Never deletes the latest image
+
+```sh
+cpflow cleanup-images -a $APP_NAME
+```
+
+### `cleanup-stale-apps`
+
+- Deletes the whole app (GVC with all workloads, all volumesets and all images) for all stale apps
+- Also unbinds the app from the secrets policy, as long as both the identity and the policy exist (and are bound)
+- Stale apps are identified based on the creation date of the latest image
+- Specify the amount of days after an app should be considered stale through `stale_app_image_deployed_days` in the `.controlplane/controlplane.yml` file
+- If `match_if_app_name_starts_with` is `true` in the `.controlplane/controlplane.yml` file, it will delete all stale apps that start with the name
+- Will ask for explicit user confirmation
+
+```sh
+cpflow cleanup-stale-apps -a $APP_NAME
+```
+
+### `config`
+
+- Displays config for each app or a specific app
+
+```sh
+# Shows the config for each app.
+cpflow config
+
+# Shows the config for a specific app.
+cpflow config -a $APP_NAME
+```
+
+### `copy-image-from-upstream`
+
+- Copies an image (by default the latest) from a source org to the current org
+- The source app must be specified either through the `CPLN_UPSTREAM` env var or `upstream` in the `.controlplane/controlplane.yml` file
+- Additionally, the token for the source org must be provided through `--upstream-token` or `-t`
+- A `cpln` profile will be temporarily created to pull the image from the source org
+
+```sh
+# Copies the latest image from the source org to the current org.
+cpflow copy-image-from-upstream -a $APP_NAME --upstream-token $UPSTREAM_TOKEN
+
+# Copies a specific image from the source org to the current org.
+cpflow copy-image-from-upstream -a $APP_NAME --upstream-token $UPSTREAM_TOKEN --image appimage:123
+```
+
+### `delete`
+
+- Deletes the whole app (GVC with all workloads, all volumesets and all images) or a specific workload
+- Also unbinds the app from the secrets policy, as long as both the identity and the policy exist (and are bound)
+- Will ask for explicit user confirmation
+- Runs a pre-deletion hook before the app is deleted if `hooks.pre_deletion` is specified in the `.controlplane/controlplane.yml` file
+- If the hook exits with a non-zero code, the command will stop executing and also exit with a non-zero code
+- Use `--skip-pre-deletion-hook` to skip the hook if specified in `controlplane.yml`
+
+```sh
+# Deletes the whole app (GVC with all workloads, all volumesets and all images).
+cpflow delete -a $APP_NAME
+
+# Deletes a specific workload.
+cpflow delete -a $APP_NAME -w $WORKLOAD_NAME
+```
+
+### `deploy-image`
+
+- Deploys the latest image to app workloads
+- Runs a release script before deploying if `release_script` is specified in the `.controlplane/controlplane.yml` file and `--run-release-phase` is provided
+- The release script is run in the context of `cpflow run` with the latest image
+- If the release script exits with a non-zero code, the command will stop executing and also exit with a non-zero code
+
+```sh
+cpflow deploy-image -a $APP_NAME
+```
+
+### `doctor`
+
+- Runs validations
+
+```sh
+# Runs all validations that don't require additional options by default.
+cpflow doctor
+
+# Runs config validation.
+cpflow doctor --validations config
+
+# Runs templates validation (requires app).
+cpflow doctor --validations templates -a $APP_NAME
+```
+
+### `env`
+
+- Displays app-specific environment variables
+
+```sh
+cpflow env -a $APP_NAME
+```
+
+### `exists`
+
+- Shell-checks if an application (GVC) exists, useful in scripts, e.g.:
+
+```sh
+if [ cpflow exists -a $APP_NAME ]; ...
+```
+
+### `generate`
+
+Creates base Control Plane config and template files
+
+```sh
+# Creates .controlplane directory with Control Plane config and other templates
+cpflow generate
+```
+
+### `info`
+
+- Displays the diff between defined/available apps/workloads (apps equal GVCs)
+- Apps that are defined but not available are displayed in red
+- Apps that are available but not defined are displayed in green
+- Apps that are both defined and available are displayed in white
+- The diff is based on what's defined in the `.controlplane/controlplane.yml` file
+
+```sh
+# Shows diff for all apps in all orgs (based on `.controlplane/controlplane.yml`).
+cpflow info
+
+# Shows diff for all apps in a specific org.
+cpflow info -o $ORG_NAME
+
+# Shows diff for a specific app.
+cpflow info -a $APP_NAME
+```
+
+### `latest-image`
+
+- Displays the latest image name
+
+```sh
+cpflow latest-image -a $APP_NAME
+```
+
+### `logs`
+
+- Light wrapper to display tailed raw logs for app/workload syntax
+- Defaults to showing the last 200 entries from the past 1 hour before tailing
+
+```sh
+# Displays logs for the default workload (`one_off_workload`).
+cpflow logs -a $APP_NAME
+
+# Displays logs for a specific workload.
+cpflow logs -a $APP_NAME -w $WORKLOAD_NAME
+
+# Displays logs for a specific replica of a workload.
+cpflow logs -a $APP_NAME -w $WORKLOAD_NAME -r $REPLICA_NAME
+
+# Uses a different limit on number of entries.
+cpflow logs -a $APP_NAME --limit 100
+
+# Uses a different loopback window.
+cpflow logs -a $APP_NAME --since 30min
+```
+
+### `maintenance`
+
+- Checks if maintenance mode is on or off for an app
+- Outputs 'on' or 'off'
+- Specify the one-off workload through `one_off_workload` in the `.controlplane/controlplane.yml` file
+- Optionally specify the maintenance workload through `maintenance_workload` in the `.controlplane/controlplane.yml` file (defaults to 'maintenance')
+- Maintenance mode is only supported for domains that use path based routing mode and have a route configured for the prefix '/' on either port 80 or 443
+
+```sh
+cpflow maintenance -a $APP_NAME
+```
+
+### `maintenance:off`
+
+- Disables maintenance mode for an app
+- Specify the one-off workload through `one_off_workload` in the `.controlplane/controlplane.yml` file
+- Optionally specify the maintenance workload through `maintenance_workload` in the `.controlplane/controlplane.yml` file (defaults to 'maintenance')
+- Maintenance mode is only supported for domains that use path based routing mode and have a route configured for the prefix '/' on either port 80 or 443
+
+```sh
+cpflow maintenance:off -a $APP_NAME
+```
+
+### `maintenance:on`
+
+- Enables maintenance mode for an app
+- Specify the one-off workload through `one_off_workload` in the `.controlplane/controlplane.yml` file
+- Optionally specify the maintenance workload through `maintenance_workload` in the `.controlplane/controlplane.yml` file (defaults to 'maintenance')
+- Maintenance mode is only supported for domains that use path based routing mode and have a route configured for the prefix '/' on either port 80 or 443
+
+```sh
+cpflow maintenance:on -a $APP_NAME
+```
+
+### `maintenance:set-page`
+
+- Sets the page for maintenance mode
+- Only works if the maintenance workload uses the `shakacode/maintenance-mode` image
+- Will set the URL as an env var `PAGE_URL` on the maintenance workload
+- Optionally specify the maintenance workload through `maintenance_workload` in the `.controlplane/controlplane.yml` file (defaults to 'maintenance')
+
+```sh
+cpflow maintenance:set-page PAGE_URL -a $APP_NAME
+```
+
+### `open`
+
+- Opens the app endpoint URL in the default browser
+
+```sh
+# Opens the endpoint of the default workload (`one_off_workload`).
+cpflow open -a $APP_NAME
+
+# Opens the endpoint of a specific workload.
+cpflow open -a $APP_NAME -w $WORKLOAD_NAME
+```
+
+### `open-console`
+
+- Opens the app console on Control Plane in the default browser
+- Can also go directly to a workload page if `--workload` is provided
+
+```sh
+cpflow open-console -a $APP_NAME
+```
+
+### `promote-app-from-upstream`
+
+- Copies the latest image from upstream, runs a release script (optional), and deploys the image
+- It performs the following steps:
+  - Runs `cpflow copy-image-from-upstream` to copy the latest image from upstream
+  - Runs `cpflow deploy-image` to deploy the image
+  - If `.controlplane/controlplane.yml` includes the `release_script`, `cpflow deploy-image` will use the `--run-release-phase` option
+  - If the release script exits with a non-zero code, the command will stop executing and also exit with a non-zero code
+
+```sh
+cpflow promote-app-from-upstream -a $APP_NAME -t $UPSTREAM_TOKEN
+```
+
+### `ps`
+
+- Shows running replicas in app
+
+```sh
+# Shows running replicas in app, for all workloads.
+cpflow ps -a $APP_NAME
+
+# Shows running replicas in app, for a specific workload.
+cpflow ps -a $APP_NAME -w $WORKLOAD_NAME
+```
+
+### `ps:restart`
+
+- Forces redeploy of workloads in app
+
+```sh
+# Forces redeploy of all workloads in app.
+cpflow ps:restart -a $APP_NAME
+
+# Forces redeploy of a specific workload in app.
+cpflow ps:restart -a $APP_NAME -w $WORKLOAD_NAME
+```
+
+### `ps:start`
+
+- Starts workloads in app
+
+```sh
+# Starts all workloads in app.
+cpflow ps:start -a $APP_NAME
+
+# Starts a specific workload in app.
+cpflow ps:start -a $APP_NAME -w $WORKLOAD_NAME
+```
+
+### `ps:stop`
+
+- Stops workloads in app
+
+```sh
+# Stops all workloads in app.
+cpflow ps:stop -a $APP_NAME
+
+# Stops a specific workload in app.
+cpflow ps:stop -a $APP_NAME -w $WORKLOAD_NAME
+
+# Stops a specific replica of a workload.
+cpflow ps:stop -a $APP_NAME -w $WORKLOAD_NAME -r $REPLICA_NAME
+```
+
+### `ps:wait`
+
+- Waits for workloads in app to be ready after re-deployment
+
+```sh
+# Waits for all workloads in app.
+cpflow ps:wait -a $APP_NAME
+
+# Waits for a specific workload in app.
+cpflow ps:swait -a $APP_NAME -w $WORKLOAD_NAME
+```
+
+### `run`
+
+- Runs one-off interactive or non-interactive replicas (analog of `heroku run`)
+- Uses `Cron` workload type and either:
+- - `cpln workload exec` for interactive mode, with CLI streaming
+- - log async fetching for non-interactive mode
+- The Dockerfile entrypoint is used as the command by default, which assumes `exec "${@}"` to be present,
+  and the args ["bash", "-c", cmd_to_run] are passed
+- The entrypoint can be overridden through `--entrypoint`, which must be a single command or a script path that exists in the container,
+  and the args ["bash", "-c", cmd_to_run] are passed,
+  unless the entrypoint is `bash`, in which case the args ["-c", cmd_to_run] are passed
+- Providing `--entrypoint none` sets the entrypoint to `bash` by default
+- If `fix_terminal_size` is `true` in the `.controlplane/controlplane.yml` file,
+  the remote terminal size will be fixed to match the local terminal size (may also be overridden through `--terminal-size`)
+- By default, all jobs use a CPU size of 1 (1 core) and a memory size of 2Gi (2 gibibytes)
+  (can be configured through `runner_job_default_cpu` and `runner_job_default_memory` in `controlplane.yml`,
+  and also overridden per job through `--cpu` and `--memory`)
+- By default, the job is stopped if it takes longer than 6 hours to finish
+  (can be configured though `runner_job_timeout` in `controlplane.yml`)
+
+```sh
+# Opens shell (bash by default).
+cpflow run -a $APP_NAME
+
+# Runs interactive command, keeps shell open, and stops job when exiting.
+cpflow run -a $APP_NAME --interactive -- rails c
+
+# Some commands are automatically detected as interactive, so no need to pass `--interactive`.
+cpflow run -a $APP_NAME -- bash
+      cpflow run -a $APP_NAME -- rails console
+      cpflow run -a $APP_NAME -- rails c
+      cpflow run -a $APP_NAME -- rails dbconsole
+      cpflow run -a $APP_NAME -- rails db
+
+# Runs non-interactive command, outputs logs, exits with the exit code of the command and stops job.
+cpflow run -a $APP_NAME -- rails db:migrate
+
+# Runs non-iteractive command, detaches, exits with 0, and prints commands to:
+# - see logs from the job
+# - stop the job
+cpflow run -a $APP_NAME --detached -- rails db:migrate
+
+# The command needs to be quoted if setting an env variable or passing args.
+cpflow run -a $APP_NAME -- 'SOME_ENV_VAR=some_value rails db:migrate'
+
+# Uses a different image (which may not be promoted yet).
+cpflow run -a $APP_NAME --image appimage:123 -- rails db:migrate # Exact image name
+cpflow run -a $APP_NAME --image latest -- rails db:migrate       # Latest sequential image
+
+# Uses a different workload than `one_off_workload` from `.controlplane/controlplane.yml`.
+cpflow run -a $APP_NAME -w other-workload -- bash
+
+# Overrides remote CPLN_TOKEN env variable with local token.
+# Useful when superuser rights are needed in remote container.
+cpflow run -a $APP_NAME --use-local-token -- bash
+
+# Replaces the existing Dockerfile entrypoint with `bash`.
+cpflow run -a $APP_NAME --entrypoint none -- rails db:migrate
+
+# Replaces the existing Dockerfile entrypoint.
+cpflow run -a $APP_NAME --entrypoint /app/alternative-entrypoint.sh -- rails db:migrate
+```
+
+### `setup-app`
+
+- Creates an app and all its workloads
+- Specify the templates for the app and workloads through `setup_app_templates` in the `.controlplane/controlplane.yml` file
+- This should only be used for temporary apps like review apps, never for persistent apps like production or staging (to update workloads for those, use 'cpflow apply-template' instead)
+- Configures app to have org-level secrets with default name "{APP_PREFIX}-secrets"
+  using org-level policy with default name "{APP_PREFIX}-secrets-policy" (names can be customized, see docs)
+- Creates identity for secrets if it does not exist
+- Use `--skip-secrets-setup` to prevent the automatic setup of secrets,
+  or set it through `skip_secrets_setup` in the `.controlplane/controlplane.yml` file
+- Runs a post-creation hook after the app is created if `hooks.post_creation` is specified in the `.controlplane/controlplane.yml` file
+- If the hook exits with a non-zero code, the command will stop executing and also exit with a non-zero code
+- Use `--skip-post-creation-hook` to skip the hook if specified in `controlplane.yml`
+
+```sh
+cpflow setup-app -a $APP_NAME
+```
+
+### `version`
+
+- Displays the current version of the CLI
+- Can also be done with `cpflow --version` or `cpflow -v`
+
+```sh
+cpflow version
+```

data/docs/dns.md

@@ -0,0 +1,15 @@
+# DNS Setup Example
+
+## Docs
+
+https://shakadocs.controlplane.com/guides/configure-domain#dns-records
+
+## Example
+
+About reactrails.com DNS, steps:
+1. create CNAME or ALIAS record pointing to rails-xxxx.cpln.app
+1. go to CPLN Domains -> create
+1. add reactrails.com copy code from there
+1. add TXT record with code as _cpln.reactrails.com
+1. hit ok on CPLN, route to rails workload when asked
+1. wait domain check and certificates created