From 42bc69175808f24e25a77447e21d3a99abc9a26b Mon Sep 17 00:00:00 2001 From: David Heinemeier Hansson Date: Sun, 19 Feb 2023 15:43:49 +0100 Subject: [PATCH] CLI doc updates Match word Language Suggest what accessories are There are also accessories Default already shown Better example Warn about secrets being shown Now also accessories Wording Clarifications Clarify how to see options General option for all Options important here too Hide subcommands Implied Simpler as just version Be concise Missing word Wordsmith Simpler and uniform words are better Clarify what exactly we're manipulating Wordsmithing Implicit Simpler language Hide subcommands Clarify its container management Just one per server Simpler --- README.md | 2 +- lib/mrsk/cli/accessory.rb | 29 +++++++++++++++-------------- lib/mrsk/cli/app.rb | 30 +++++++++++++++--------------- lib/mrsk/cli/base.rb | 4 ++-- lib/mrsk/cli/build.rb | 12 ++++++------ lib/mrsk/cli/healthcheck.rb | 4 +++- lib/mrsk/cli/main.rb | 29 +++++++++++++++-------------- lib/mrsk/cli/prune.rb | 2 +- lib/mrsk/cli/registry.rb | 4 ++-- lib/mrsk/cli/server.rb | 2 +- lib/mrsk/cli/traefik.rb | 12 ++++++------ 11 files changed, 67 insertions(+), 63 deletions(-) diff --git a/README.md b/README.md index 2d87838f..0c53001c 100644 --- a/README.md +++ b/README.md @@ -447,7 +447,7 @@ mrsk app exec -i 'bin/rails console' ``` -### Running details to see state of containers +### Running details to show state of containers You can see the state of your servers by running `mrsk details`: diff --git a/lib/mrsk/cli/accessory.rb b/lib/mrsk/cli/accessory.rb index 78566462..b658609c 100644 --- a/lib/mrsk/cli/accessory.rb +++ b/lib/mrsk/cli/accessory.rb @@ -1,5 +1,5 @@ class Mrsk::Cli::Accessory < Mrsk::Cli::Base - desc "boot [NAME]", "Boot accessory service on host (use NAME=all to boot all accessories)" + desc "boot [NAME]", "Boot new accessory service on host (use NAME=all to boot all accessories)" def boot(name) if name == "all" MRSK.accessory_names.each { |accessory_name| boot(accessory_name) } @@ -18,7 +18,7 @@ class Mrsk::Cli::Accessory < Mrsk::Cli::Base end end - desc "upload [NAME]", "Upload accessory files to host" + desc "upload [NAME]", "Upload accessory files to host", hide: true def upload(name) with_accessory(name) do |accessory| on(accessory.host) do @@ -33,7 +33,7 @@ class Mrsk::Cli::Accessory < Mrsk::Cli::Base end end - desc "directories [NAME]", "Create accessory directories on host" + desc "directories [NAME]", "Create accessory directories on host", hide: true def directories(name) with_accessory(name) do |accessory| on(accessory.host) do @@ -44,7 +44,7 @@ class Mrsk::Cli::Accessory < Mrsk::Cli::Base end end - desc "reboot [NAME]", "Reboot accessory on host (stop container, remove container, start new container)" + desc "reboot [NAME]", "Reboot existing accessory on host (stop container, remove container, start new container)" def reboot(name) with_accessory(name) do |accessory| stop(name) @@ -53,7 +53,7 @@ class Mrsk::Cli::Accessory < Mrsk::Cli::Base end end - desc "start [NAME]", "Start existing accessory on host" + desc "start [NAME]", "Start existing accessory container on host" def start(name) with_accessory(name) do |accessory| on(accessory.host) do @@ -63,7 +63,7 @@ class Mrsk::Cli::Accessory < Mrsk::Cli::Base end end - desc "stop [NAME]", "Stop accessory on host" + desc "stop [NAME]", "Stop existing accessory container on host" def stop(name) with_accessory(name) do |accessory| on(accessory.host) do @@ -73,7 +73,7 @@ class Mrsk::Cli::Accessory < Mrsk::Cli::Base end end - desc "restart [NAME]", "Restart accessory on host" + desc "restart [NAME]", "Restart existing accessory container on host" def restart(name) with_accessory(name) do stop(name) @@ -81,7 +81,7 @@ class Mrsk::Cli::Accessory < Mrsk::Cli::Base end end - desc "details [NAME]", "Display details about accessory on host (use NAME=all to boot all accessories)" + desc "details [NAME]", "Show details about accessory on host (use NAME=all to show all accessories)" def details(name) if name == "all" MRSK.accessory_names.each { |accessory_name| details(accessory_name) } @@ -92,7 +92,7 @@ class Mrsk::Cli::Accessory < Mrsk::Cli::Base end end - desc "exec [NAME] [CMD]", "Execute a custom command on servers" + desc "exec [NAME] [CMD]", "Execute a custom command on servers (use --help to show options)" option :interactive, aliases: "-i", type: :boolean, default: false, desc: "Execute command over ssh for an interactive shell (use for console/bash)" option :reuse, type: :boolean, default: false, desc: "Reuse currently running container instead of starting a new one" def exec(name, cmd) @@ -123,7 +123,7 @@ class Mrsk::Cli::Accessory < Mrsk::Cli::Base end end - desc "logs [NAME]", "Show log lines from accessory on host" + desc "logs [NAME]", "Show log lines from accessory on host (use --help to show options)" option :since, aliases: "-s", desc: "Show logs since timestamp (e.g. 2013-01-02T13:23:37Z) or relative (e.g. 42m for 42 minutes)" option :lines, type: :numeric, aliases: "-n", desc: "Number of log lines to pull from each server" option :grep, aliases: "-g", desc: "Show lines with grep match only (use this to fetch specific requests by id)" @@ -149,7 +149,8 @@ class Mrsk::Cli::Accessory < Mrsk::Cli::Base end end - desc "remove [NAME]", "Remove accessory container and image from host (use NAME=all to boot all accessories)" + desc "remove [NAME]", "Remove accessory container and image from host (use NAME=all to remove all accessories)" + option :confirmed, aliases: "-y", type: :boolean, default: false, desc: "Proceed without confirmation question" def remove(name) if name == "all" MRSK.accessory_names.each { |accessory_name| remove(accessory_name) } @@ -163,7 +164,7 @@ class Mrsk::Cli::Accessory < Mrsk::Cli::Base end end - desc "remove_container [NAME]", "Remove accessory container from host" + desc "remove_container [NAME]", "Remove accessory container from host", hide: true def remove_container(name) with_accessory(name) do |accessory| on(accessory.host) do @@ -173,7 +174,7 @@ class Mrsk::Cli::Accessory < Mrsk::Cli::Base end end - desc "remove_image [NAME]", "Remove accessory image from host" + desc "remove_image [NAME]", "Remove accessory image from host", hide: true def remove_image(name) with_accessory(name) do |accessory| on(accessory.host) do @@ -183,7 +184,7 @@ class Mrsk::Cli::Accessory < Mrsk::Cli::Base end end - desc "remove_service_directory [NAME]", "Remove accessory directory used for uploaded files and data directories from host" + desc "remove_service_directory [NAME]", "Remove accessory directory used for uploaded files and data directories from host", hide: true def remove_service_directory(name) with_accessory(name) do |accessory| on(accessory.host) do diff --git a/lib/mrsk/cli/app.rb b/lib/mrsk/cli/app.rb index 9354709a..baa015dd 100644 --- a/lib/mrsk/cli/app.rb +++ b/lib/mrsk/cli/app.rb @@ -28,7 +28,7 @@ class Mrsk::Cli::App < Mrsk::Cli::Base end end - desc "start", "Start existing app on servers (use --version= to designate specific version)" + desc "start", "Start existing app container on servers" def start on(MRSK.hosts) do execute *MRSK.auditor.record("Started app version #{MRSK.version}"), verbosity: :debug @@ -36,7 +36,7 @@ class Mrsk::Cli::App < Mrsk::Cli::Base end end - desc "stop", "Stop app on servers" + desc "stop", "Stop app container on servers" def stop on(MRSK.hosts) do execute *MRSK.auditor.record("Stopped app"), verbosity: :debug @@ -44,12 +44,12 @@ class Mrsk::Cli::App < Mrsk::Cli::Base end end - desc "details", "Display details about app containers" + desc "details", "Show details about app containers" def details on(MRSK.hosts) { |host| puts_by_host host, capture_with_info(*MRSK.app.info) } end - desc "exec [CMD]", "Execute a custom command on servers" + desc "exec [CMD]", "Execute a custom command on servers (use --help to show options)" option :interactive, aliases: "-i", type: :boolean, default: false, desc: "Execute command over ssh for an interactive shell (use for console/bash)" option :reuse, type: :boolean, default: false, desc: "Reuse currently running container instead of starting a new one" def exec(cmd) @@ -91,21 +91,21 @@ class Mrsk::Cli::App < Mrsk::Cli::Base end end - desc "containers", "List all the app containers currently on servers" + desc "containers", "Show app containers on servers" def containers on(MRSK.hosts) { |host| puts_by_host host, capture_with_info(*MRSK.app.list_containers) } end - desc "images", "List all the app images currently on servers" + desc "images", "Show app images on servers" def images on(MRSK.hosts) { |host| puts_by_host host, capture_with_info(*MRSK.app.list_images) } end - desc "logs", "Show lines from app on servers" - option :since, aliases: "-s", desc: "Show logs since timestamp (e.g. 2013-01-02T13:23:37Z) or relative (e.g. 42m for 42 minutes)" - option :lines, type: :numeric, aliases: "-n", desc: "Number of log lines to pull from each server" + desc "logs", "Show log lines from app on servers (use --help to show options)" + option :since, aliases: "-s", desc: "Show lines since timestamp (e.g. 2013-01-02T13:23:37Z) or relative (e.g. 42m for 42 minutes)" + option :lines, type: :numeric, aliases: "-n", desc: "Number of lines to show from each server" option :grep, aliases: "-g", desc: "Show lines with grep match only (use this to fetch specific requests by id)" - option :follow, aliases: "-f", desc: "Follow logs on primary server (or specific host set by --hosts)" + option :follow, aliases: "-f", desc: "Follow log on primary server (or specific host set by --hosts)" def logs # FIXME: Catch when app containers aren't running @@ -137,7 +137,7 @@ class Mrsk::Cli::App < Mrsk::Cli::Base remove_images end - desc "remove_container [VERSION]", "Remove app container with given version from servers" + desc "remove_container [VERSION]", "Remove app container with given version from servers", hide: true def remove_container(version) on(MRSK.hosts) do execute *MRSK.auditor.record("Removed app container with version #{version}"), verbosity: :debug @@ -145,7 +145,7 @@ class Mrsk::Cli::App < Mrsk::Cli::Base end end - desc "remove_containers", "Remove all app containers from servers" + desc "remove_containers", "Remove all app containers from servers", hide: true def remove_containers on(MRSK.hosts) do execute *MRSK.auditor.record("Removed all app containers"), verbosity: :debug @@ -153,7 +153,7 @@ class Mrsk::Cli::App < Mrsk::Cli::Base end end - desc "remove_images", "Remove all app images from servers" + desc "remove_images", "Remove all app images from servers", hide: true def remove_images on(MRSK.hosts) do execute *MRSK.auditor.record("Removed all app images"), verbosity: :debug @@ -161,8 +161,8 @@ class Mrsk::Cli::App < Mrsk::Cli::Base end end - desc "current_version", "Shows the version currently running" - def current_version + desc "version", "Show app version currently running on servers" + def version on(MRSK.hosts) { |host| puts_by_host host, capture_with_info(*MRSK.app.current_running_version).strip } end diff --git a/lib/mrsk/cli/base.rb b/lib/mrsk/cli/base.rb index e89f4591..23dcb9d0 100644 --- a/lib/mrsk/cli/base.rb +++ b/lib/mrsk/cli/base.rb @@ -17,8 +17,8 @@ module Mrsk::Cli class_option :hosts, aliases: "-h", desc: "Run commands on these hosts instead of all (separate by comma)" class_option :roles, aliases: "-r", desc: "Run commands on these roles instead of all (separate by comma)" - class_option :config_file, aliases: "-c", default: "config/deploy.yml", desc: "Path to config file (default: config/deploy.yml)" - class_option :destination, aliases: "-d", desc: "Specify destination to be used for config file (west -> deploy.west.yml)" + class_option :config_file, aliases: "-c", default: "config/deploy.yml", desc: "Path to config file" + class_option :destination, aliases: "-d", desc: "Specify destination to be used for config file (staging -> deploy.staging.yml)" def initialize(*) super diff --git a/lib/mrsk/cli/build.rb b/lib/mrsk/cli/build.rb index c16fcf55..8cff1310 100644 --- a/lib/mrsk/cli/build.rb +++ b/lib/mrsk/cli/build.rb @@ -1,11 +1,11 @@ class Mrsk::Cli::Build < Mrsk::Cli::Base - desc "deliver", "Deliver a newly built app image to servers" + desc "deliver", "Build app and push app image to registry then pull image on servers" def deliver invoke :push invoke :pull end - desc "push", "Build locally and push app image to registry" + desc "push", "Build and push app image to registry" def push cli = self @@ -26,7 +26,7 @@ class Mrsk::Cli::Build < Mrsk::Cli::Base end end - desc "pull", "Pull app image from the registry onto servers" + desc "pull", "Pull app image from registry onto servers" def pull on(MRSK.hosts) do execute *MRSK.auditor.record("Pulled image with version #{MRSK.version}"), verbosity: :debug @@ -34,7 +34,7 @@ class Mrsk::Cli::Build < Mrsk::Cli::Base end end - desc "create", "Create a local build setup" + desc "create", "Create a build setup" def create run_locally do begin @@ -51,7 +51,7 @@ class Mrsk::Cli::Build < Mrsk::Cli::Base end end - desc "remove", "Remove local build setup" + desc "remove", "Remove build setup" def remove run_locally do debug "Using builder: #{MRSK.builder.name}" @@ -59,7 +59,7 @@ class Mrsk::Cli::Build < Mrsk::Cli::Base end end - desc "details", "Show the name of the configured builder" + desc "details", "Show build setup" def details run_locally do puts "Builder: #{MRSK.builder.name}" diff --git a/lib/mrsk/cli/healthcheck.rb b/lib/mrsk/cli/healthcheck.rb index f348244a..a9fcf803 100644 --- a/lib/mrsk/cli/healthcheck.rb +++ b/lib/mrsk/cli/healthcheck.rb @@ -1,5 +1,7 @@ class Mrsk::Cli::Healthcheck < Mrsk::Cli::Base - desc "perform", "Health check the current version of the app" + default_command :perform + + desc "perform", "Health check current app version" def perform on(MRSK.primary_host) do begin diff --git a/lib/mrsk/cli/main.rb b/lib/mrsk/cli/main.rb index 8dac14ac..3e1381a1 100644 --- a/lib/mrsk/cli/main.rb +++ b/lib/mrsk/cli/main.rb @@ -1,5 +1,5 @@ class Mrsk::Cli::Main < Mrsk::Cli::Base - desc "setup", "Setup all accessories and deploy the app to servers" + desc "setup", "Setup all accessories and deploy app to servers" def setup print_runtime do invoke "mrsk:cli:server:bootstrap" @@ -8,7 +8,7 @@ class Mrsk::Cli::Main < Mrsk::Cli::Base end end - desc "deploy", "Deploy the app to servers" + desc "deploy", "Deploy app to servers" def deploy runtime = print_runtime do say "Ensure Docker is installed...", :magenta @@ -35,7 +35,7 @@ class Mrsk::Cli::Main < Mrsk::Cli::Base audit_broadcast "Deployed app in #{runtime.to_i} seconds" end - desc "redeploy", "Deploy new version of the app to servers (without bootstrapping servers, starting Traefik, pruning, and registry login)" + desc "redeploy", "Deploy app to servers without bootstrapping servers, starting Traefik, pruning, and registry login" def redeploy runtime = print_runtime do say "Build and push app image...", :magenta @@ -50,7 +50,7 @@ class Mrsk::Cli::Main < Mrsk::Cli::Base audit_broadcast "Redeployed app in #{runtime.to_i} seconds" end - desc "rollback [VERSION]", "Rollback the app to VERSION" + desc "rollback [VERSION]", "Rollback app to VERSION" def rollback(version) MRSK.version = version @@ -68,7 +68,7 @@ class Mrsk::Cli::Main < Mrsk::Cli::Base end end - desc "details", "Display details about Traefik and app containers" + desc "details", "Show details about all containers" def details invoke "mrsk:cli:traefik:details" invoke "mrsk:cli:app:details" @@ -82,7 +82,7 @@ class Mrsk::Cli::Main < Mrsk::Cli::Base end end - desc "config", "Show combined config" + desc "config", "Show combined config (including secrets!)" def config run_locally do puts MRSK.config.to_h.to_yaml @@ -132,40 +132,41 @@ class Mrsk::Cli::Main < Mrsk::Cli::Base File.write(env_path, ERB.new(File.read(env_template_path)).result, perm: 0600) end - desc "remove", "Remove Traefik, app, and registry session from servers" + desc "remove", "Remove Traefik, app, accessories, and registry session from servers" + option :confirmed, aliases: "-y", type: :boolean, default: false, desc: "Proceed without confirmation question" def remove invoke "mrsk:cli:traefik:remove" invoke "mrsk:cli:app:remove" invoke "mrsk:cli:registry:logout" end - desc "version", "Display the MRSK version" + desc "version", "Show MRSK version" def version puts Mrsk::VERSION end - desc "accessory", "Manage the accessories" + desc "accessory", "Manage accessories (db/redis/search)" subcommand "accessory", Mrsk::Cli::Accessory - desc "app", "Manage the application" + desc "app", "Manage application" subcommand "app", Mrsk::Cli::App - desc "build", "Build the application image" + desc "build", "Build application image" subcommand "build", Mrsk::Cli::Build - desc "healthcheck", "Healthcheck the application" + desc "healthcheck", "Healthcheck application" subcommand "healthcheck", Mrsk::Cli::Healthcheck desc "prune", "Prune old application images and containers" subcommand "prune", Mrsk::Cli::Prune - desc "registry", "Login and out of the image registry" + desc "registry", "Login and -out of the image registry" subcommand "registry", Mrsk::Cli::Registry desc "server", "Bootstrap servers with Docker" subcommand "server", Mrsk::Cli::Server - desc "traefik", "Manage the Traefik load balancer" + desc "traefik", "Manage Traefik load balancer" subcommand "traefik", Mrsk::Cli::Traefik private diff --git a/lib/mrsk/cli/prune.rb b/lib/mrsk/cli/prune.rb index 77856444..63093e84 100644 --- a/lib/mrsk/cli/prune.rb +++ b/lib/mrsk/cli/prune.rb @@ -13,7 +13,7 @@ class Mrsk::Cli::Prune < Mrsk::Cli::Base end end - desc "containers", "Prune stopped containers for the service older than 3 days" + desc "containers", "Prune stopped containers older than 3 days" def containers on(MRSK.hosts) do execute *MRSK.auditor.record("Pruned containers"), verbosity: :debug diff --git a/lib/mrsk/cli/registry.rb b/lib/mrsk/cli/registry.rb index 5342c32f..f854d8f9 100644 --- a/lib/mrsk/cli/registry.rb +++ b/lib/mrsk/cli/registry.rb @@ -1,5 +1,5 @@ class Mrsk::Cli::Registry < Mrsk::Cli::Base - desc "login", "Login to the registry locally and remotely" + desc "login", "Log in to registry locally and remotely" def login run_locally { execute *MRSK.registry.login } on(MRSK.hosts) { execute *MRSK.registry.login } @@ -7,7 +7,7 @@ class Mrsk::Cli::Registry < Mrsk::Cli::Base puts e.message end - desc "logout", "Logout of the registry remotely" + desc "logout", "Log out of registry remotely" def logout on(MRSK.hosts) { execute *MRSK.registry.logout } rescue ArgumentError => e diff --git a/lib/mrsk/cli/server.rb b/lib/mrsk/cli/server.rb index ce8ab2cd..9030ffd6 100644 --- a/lib/mrsk/cli/server.rb +++ b/lib/mrsk/cli/server.rb @@ -1,5 +1,5 @@ class Mrsk::Cli::Server < Mrsk::Cli::Base - desc "bootstrap", "Ensure Docker is installed on the servers" + desc "bootstrap", "Ensure Docker is installed on servers" def bootstrap on(MRSK.hosts + MRSK.accessory_hosts) { execute "which docker || (apt-get update -y && apt-get install docker.io -y)" } end diff --git a/lib/mrsk/cli/traefik.rb b/lib/mrsk/cli/traefik.rb index eed9ee17..daef467b 100644 --- a/lib/mrsk/cli/traefik.rb +++ b/lib/mrsk/cli/traefik.rb @@ -11,7 +11,7 @@ class Mrsk::Cli::Traefik < Mrsk::Cli::Base invoke :boot end - desc "start", "Start existing Traefik on servers" + desc "start", "Start existing Traefik container on servers" def start on(MRSK.traefik_hosts) do execute *MRSK.auditor.record("Started traefik"), verbosity: :debug @@ -19,7 +19,7 @@ class Mrsk::Cli::Traefik < Mrsk::Cli::Base end end - desc "stop", "Stop Traefik on servers" + desc "stop", "Stop existing Traefik container on servers" def stop on(MRSK.traefik_hosts) do execute *MRSK.auditor.record("Stopped traefik"), verbosity: :debug @@ -27,13 +27,13 @@ class Mrsk::Cli::Traefik < Mrsk::Cli::Base end end - desc "restart", "Restart Traefik on servers" + desc "restart", "Restart existing Traefik container on servers" def restart invoke :stop invoke :start end - desc "details", "Display details about Traefik containers from servers" + desc "details", "Show details about Traefik container from servers" def details on(MRSK.traefik_hosts) { |host| puts_by_host host, capture_with_info(*MRSK.traefik.info), type: "Traefik" } end @@ -69,7 +69,7 @@ class Mrsk::Cli::Traefik < Mrsk::Cli::Base invoke :remove_image end - desc "remove_container", "Remove Traefik container from servers" + desc "remove_container", "Remove Traefik container from servers", hide: true def remove_container on(MRSK.traefik_hosts) do execute *MRSK.auditor.record("Removed traefik container"), verbosity: :debug @@ -77,7 +77,7 @@ class Mrsk::Cli::Traefik < Mrsk::Cli::Base end end - desc "remove_container", "Remove Traefik image from servers" + desc "remove_container", "Remove Traefik image from servers", hide: true def remove_image on(MRSK.traefik_hosts) do execute *MRSK.auditor.record("Removed traefik image"), verbosity: :debug