spacebar/kamal
1
0
Fork 0
Code Issues Pull Requests Actions Packages Projects Releases Wiki Activity

CLI doc updates

Browse Source 
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
This commit is contained in:
David Heinemeier Hansson
2023-02-19 15:43:49 +01:00
parent e5c4cb0344
commit 42bc691758
11 changed files with 67 additions and 63 deletions
Download Patch File Download Diff File Expand all files Collapse all files

29
lib/mrsk/cli/accessory.rb
View File

@@ -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

30
lib/mrsk/cli/app.rb
View File

@@ -28,7 +28,7 @@ class Mrsk::Cli::App < Mrsk::Cli::Base
end
end
desc "start", "Start existing app on servers (use --version=<git-hash> 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

4
lib/mrsk/cli/base.rb
View File

@@ -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

12
lib/mrsk/cli/build.rb
View File

@@ -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}"

4
lib/mrsk/cli/healthcheck.rb
View File

@@ -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

29
lib/mrsk/cli/main.rb
View File

@@ -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

2
lib/mrsk/cli/prune.rb
View File

@@ -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

4
lib/mrsk/cli/registry.rb
View File

@@ -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

2
lib/mrsk/cli/server.rb
View File

@@ -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

12
lib/mrsk/cli/traefik.rb
View File

@@ -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