diff --git a/README.md b/README.md index 4762aa9..d6f680d 100644 --- a/README.md +++ b/README.md @@ -35,7 +35,7 @@ redis:exists # check if the redis service redis:export # export a dump of the redis service database redis:expose # expose a redis service on custom port if provided (random port otherwise) redis:import # import a dump into the redis service database -redis:info [--single-info-flag] # print the connection information +redis:info [--single-info-flag] # print the service information redis:link [--link-flags...] # link the redis service to the app redis:linked # check if the redis service is linked to an app redis:links # list all apps linked to the redis service @@ -55,20 +55,7 @@ redis:upgrade [--upgrade-flags...] # upgrade service t Help for any commands can be displayed by specifying the command as an argument to redis:help. Please consult the `redis:help` command for any undocumented commands. ### Basic Usage -### list all redis services -```shell -# usage -dokku redis:list -``` - -examples: - -List all services: - -```shell -dokku redis:list -``` ### create a redis service ```shell @@ -76,15 +63,13 @@ dokku redis:list dokku redis:create [--create-flags...] ``` -examples: - Create a redis service named lolipop: ```shell dokku redis:create lolipop ``` -You can also specify the image and image version to use for the service. It *must* be compatible with the ${plugin_image} image. : +You can also specify the image and image version to use for the service. It *must* be compatible with the ${plugin_image} image. ```shell export REDIS_IMAGE="${PLUGIN_IMAGE}" @@ -92,21 +77,20 @@ export REDIS_IMAGE_VERSION="${PLUGIN_IMAGE_VERSION}" dokku redis:create lolipop ``` -You can also specify custom environment variables to start the redis service in semi-colon separated form. : +You can also specify custom environment variables to start the redis service in semi-colon separated form. ```shell export REDIS_CUSTOM_ENV="USER=alpha;HOST=beta" dokku redis:create lolipop ``` -### print the connection information + +### print the service information ```shell # usage dokku redis:info [--single-info-flag] ``` -examples: - Get connection information as follows: ```shell @@ -127,6 +111,20 @@ dokku redis:info lolipop --service-root dokku redis:info lolipop --status dokku redis:info lolipop --version ``` + +### list all redis services + +```shell +# usage +dokku redis:list +``` + +List all services: + +```shell +dokku redis:list +``` + ### print the most recent log(s) for this service ```shell @@ -134,8 +132,6 @@ dokku redis:info lolipop --version dokku redis:logs [-t|--tail] ``` -examples: - You can tail logs for a particular service: ```shell @@ -147,6 +143,7 @@ By default, logs will not be tailed, but you can do this with the --tail flag: ```shell dokku redis:logs lolipop --tail ``` + ### link the redis service to the app ```shell @@ -154,9 +151,7 @@ dokku redis:logs lolipop --tail dokku redis:link [--link-flags...] ``` -examples: - -A redis service can be linked to a container. This will use native docker links via the docker-options plugin. Here we link it to our 'playground' app. : +A redis service can be linked to a container. This will use native docker links via the docker-options plugin. Here we link it to our 'playground' app. > NOTE: this will restart your app @@ -187,7 +182,7 @@ The host exposed here only works internally in docker containers. If you want yo dokku redis:link other_service playground ``` -It is possible to change the protocol for redis_url by setting the environment variable redis_database_scheme on the app. Doing so will after linking will cause the plugin to think the service is not linked, and we advise you to unlink before proceeding. : +It is possible to change the protocol for redis_url by setting the environment variable redis_database_scheme on the app. Doing so will after linking will cause the plugin to think the service is not linked, and we advise you to unlink before proceeding. ```shell dokku config:set playground REDIS_DATABASE_SCHEME=redis2 @@ -199,6 +194,7 @@ This will cause redis_url to be set as: ``` redis2://lolipop:SOME_PASSWORD@dokku-redis-lolipop:6379/lolipop ``` + ### unlink the redis service from the app ```shell @@ -206,8 +202,6 @@ redis2://lolipop:SOME_PASSWORD@dokku-redis-lolipop:6379/lolipop dokku redis:unlink ``` -examples: - You can unlink a redis service: > NOTE: this will restart your app and unset related environment variables @@ -215,20 +209,6 @@ You can unlink a redis service: ```shell dokku redis:unlink lolipop playground ``` -### delete the redis service/data/container if there are no links left - -```shell -# usage -dokku redis:destroy [-f|--force] -``` - -examples: - -Destroy the service, it's data, and the running container: - -```shell -dokku redis:destroy lolipop -``` ### Service Lifecycle @@ -241,13 +221,12 @@ The lifecycle of each service can be managed through the following commands: dokku redis:connect ``` -examples: - Connect to the service via the redis connection tool: ```shell dokku redis:connect lolipop ``` + ### enter or run a command in a running redis service container ```shell @@ -255,19 +234,18 @@ dokku redis:connect lolipop dokku redis:enter ``` -examples: - -A bash prompt can be opened against a running service. Filesystem changes will not be saved to disk. : +A bash prompt can be opened against a running service. Filesystem changes will not be saved to disk. ```shell dokku redis:enter lolipop ``` -You may also run a command directly against the service. Filesystem changes will not be saved to disk. : +You may also run a command directly against the service. Filesystem changes will not be saved to disk. ```shell dokku redis:enter lolipop touch /tmp/test ``` + ### expose a redis service on custom port if provided (random port otherwise) ```shell @@ -275,13 +253,12 @@ dokku redis:enter lolipop touch /tmp/test dokku redis:expose ``` -examples: - Expose the service on the service's normal ports, allowing access to it from the public interface (0. 0. 0. 0): ```shell dokku redis:expose lolipop ${PLUGIN_DATASTORE_PORTS[@]} ``` + ### unexpose a previously exposed redis service ```shell @@ -289,13 +266,12 @@ dokku redis:expose lolipop ${PLUGIN_DATASTORE_PORTS[@]} dokku redis:unexpose ``` -examples: - Unexpose the service, removing access to it from the public interface (0. 0. 0. 0): ```shell dokku redis:unexpose lolipop ``` + ### promote service as REDIS_URL in ```shell @@ -303,8 +279,6 @@ dokku redis:unexpose lolipop dokku redis:promote ``` -examples: - If you have a redis service linked to an app and try to link another redis service another link environment variable will be generated automatically: ``` @@ -326,20 +300,7 @@ REDIS_URL=redis://other_service:ANOTHER_PASSWORD@dokku-redis-other-service:6379/ DOKKU_REDIS_BLUE_URL=redis://other_service:ANOTHER_PASSWORD@dokku-redis-other-service:6379/other_service DOKKU_REDIS_SILVER_URL=redis://lolipop:SOME_PASSWORD@dokku-redis-lolipop:6379/lolipop ``` -### graceful shutdown and restart of the redis service container -```shell -# usage -dokku redis:restart -``` - -examples: - -Restart the service: - -```shell -dokku redis:restart lolipop -``` ### start a previously stopped redis service ```shell @@ -347,13 +308,12 @@ dokku redis:restart lolipop dokku redis:start ``` -examples: - Start the service: ```shell dokku redis:start lolipop ``` + ### stop a running redis service ```shell @@ -361,13 +321,25 @@ dokku redis:start lolipop dokku redis:stop ``` -examples: - Stop the service and the running container: ```shell dokku redis:stop lolipop ``` + +### graceful shutdown and restart of the redis service container + +```shell +# usage +dokku redis:restart +``` + +Restart the service: + +```shell +dokku redis:restart lolipop +``` + ### upgrade service to the specified versions ```shell @@ -375,8 +347,6 @@ dokku redis:stop lolipop dokku redis:upgrade [--upgrade-flags...] ``` -examples: - You can upgrade an existing service to a new image or image-version: ```shell @@ -394,13 +364,12 @@ Service scripting can be executed using the following commands: dokku redis:app-links ``` -examples: - -List all redis services that are linked to the 'playground' app. : +List all redis services that are linked to the 'playground' app. ```shell dokku redis:app-links playground ``` + ### create container then copy data from into ```shell @@ -408,13 +377,12 @@ dokku redis:app-links playground dokku redis:clone [--clone-flags...] ``` -examples: - You can clone an existing service to a new one: ```shell dokku redis:clone lolipop lolipop-2 ``` + ### check if the redis service exists ```shell @@ -422,13 +390,12 @@ dokku redis:clone lolipop lolipop-2 dokku redis:exists ``` -examples: - -Here we check if the lolipop redis service exists. : +Here we check if the lolipop redis service exists. ```shell dokku redis:exists lolipop ``` + ### check if the redis service is linked to an app ```shell @@ -436,13 +403,12 @@ dokku redis:exists lolipop dokku redis:linked ``` -examples: - -Here we check if the lolipop redis service is linked to the 'playground' app. : +Here we check if the lolipop redis service is linked to the 'playground' app. ```shell dokku redis:linked lolipop playground ``` + ### list all apps linked to the redis service ```shell @@ -450,9 +416,7 @@ dokku redis:linked lolipop playground dokku redis:links ``` -examples: - -List all apps linked to the 'lolipop' redis service. : +List all apps linked to the 'lolipop' redis service. ```shell dokku redis:links lolipop @@ -469,13 +433,12 @@ The underlying service data can be imported and exported with the following comm dokku redis:import ``` -examples: - Import a datastore dump: ```shell dokku redis:import lolipop < database.dump ``` + ### export a dump of the redis service database ```shell @@ -483,8 +446,6 @@ dokku redis:import lolipop < database.dump dokku redis:export ``` -examples: - By default, datastore output is exported to stdout: ```shell @@ -512,8 +473,6 @@ Backups can be performed using the backup commands: dokku redis:backup-auth ``` -examples: - Setup s3 backup authentication: ```shell @@ -537,6 +496,7 @@ More specific example for minio auth: ```shell dokku redis:backup-auth lolipop MINIO_ACCESS_KEY_ID MINIO_SECRET_ACCESS_KEY us-east-1 s3v4 https://YOURMINIOSERVICE ``` + ### removes backup authentication for the redis service ```shell @@ -544,13 +504,12 @@ dokku redis:backup-auth lolipop MINIO_ACCESS_KEY_ID MINIO_SECRET_ACCESS_KEY us-e dokku redis:backup-deauth ``` -examples: - Remove s3 authentication: ```shell dokku redis:backup-deauth lolipop ``` + ### creates a backup of the redis service to an existing s3 bucket ```shell @@ -558,13 +517,12 @@ dokku redis:backup-deauth lolipop dokku redis:backup [--use-iam] ``` -examples: - Backup the 'lolipop' service to the 'my-s3-bucket' bucket on aws: ```shell dokku redis:backup lolipop my-s3-bucket --use-iam ``` + ### sets encryption for all future backups of redis service ```shell @@ -572,13 +530,12 @@ dokku redis:backup lolipop my-s3-bucket --use-iam dokku redis:backup-set-encryption ``` -examples: - Set a gpg passphrase for backups: ```shell dokku redis:backup-set-encryption lolipop ``` + ### unsets encryption for future backups of the redis service ```shell @@ -586,13 +543,12 @@ dokku redis:backup-set-encryption lolipop dokku redis:backup-unset-encryption ``` -examples: - Unset a gpg encryption key for backups: ```shell dokku redis:backup-unset-encryption lolipop ``` + ### schedules a backup of the redis service ```shell @@ -600,8 +556,6 @@ dokku redis:backup-unset-encryption lolipop dokku redis:backup-schedule [--use-iam] ``` -examples: - Schedule a backup: > 'schedule' is a crontab expression, eg. "0 3 * * *" for each day at 3am @@ -615,6 +569,7 @@ Schedule a backup and authenticate via iam: ```shell dokku redis:backup-schedule lolipop "0 3 * * *" my-s3-bucket --use-iam ``` + ### cat the contents of the configured backup cronfile for the service ```shell @@ -622,13 +577,12 @@ dokku redis:backup-schedule lolipop "0 3 * * *" my-s3-bucket --use-iam dokku redis:backup-schedule-cat ``` -examples: - Cat the contents of the configured backup cronfile for the service: ```shell dokku redis:backup-schedule-cat lolipop ``` + ### unschedules the backup of the redis service ```shell @@ -636,8 +590,6 @@ dokku redis:backup-schedule-cat lolipop dokku redis:backup-unschedule ``` -examples: - Remove the scheduled backup from cron: ```shell diff --git a/bin/generate b/bin/generate index 805ee7c..3ddf821 100755 --- a/bin/generate +++ b/bin/generate @@ -5,6 +5,17 @@ import os import re +def compile(service, version, alias, scheme, ports, unimplemented, dokku_version): + return "\n\n".join([ + header(service), + description(service, version), + requirements_section(dokku_version), + installation_section(service, dokku_version), + commands_section(service, alias, scheme, ports, unimplemented), + usage_section(service, alias, scheme, ports, unimplemented), + ]).replace("\n\n\n\n\n", "\n").replace("\n\n\n\n", "\n").replace("\n\n\n", "\n\n") + + def header(service): return " ".join([ f"# dokku {service}", @@ -17,7 +28,7 @@ def description(service, version): return f"Official {service} plugin for dokku. Currently defaults to installing [{service} {version}](https://hub.docker.com/_/{service}/)." -def requirements(dokku_version): +def requirements_section(dokku_version): return "\n".join([ "## Requirements", "", @@ -26,7 +37,7 @@ def requirements(dokku_version): ]) -def installation(service, dokku_version): +def installation_section(service, dokku_version): return "\n".join([ "## Installation", "", @@ -37,7 +48,7 @@ def installation(service, dokku_version): ]) -def commands(service, alias, scheme, ports): +def commands_section(service, alias, scheme, ports, unimplemented): content = [ "## Commands", "", @@ -50,6 +61,8 @@ def commands(service, alias, scheme, ports): command_list = [] descriptions = [] for filename in subcommands: + if filename in unimplemented: + continue data = command_data(filename, service, alias, scheme, ports) description = data["description"] arguments = data["arguments_string"] @@ -68,77 +81,65 @@ def commands(service, alias, scheme, ports): return "\n".join(content) -def usage(service, alias, scheme, ports): +def usage_section(service, alias, scheme, ports, unimplemented): return "\n\n".join([ "## Usage", f"Help for any commands can be displayed by specifying the command as an argument to {service}:help. Please consult the `{service}:help` command for any undocumented commands.", - usage_intro(service, alias, scheme, ports), - usage_lifecycle(service, alias, scheme, ports), - usage_automation(service, alias, scheme, ports), - usage_data_management(service, alias, scheme, ports), - usage_backup(service, alias, scheme, ports), - usage_docker_pull(service, alias, scheme, ports), + usage_intro(service, alias, scheme, ports, unimplemented), + usage_lifecycle(service, alias, scheme, ports, unimplemented), + usage_automation(service, alias, scheme, ports, unimplemented), + usage_data_management(service, alias, scheme, ports, unimplemented), + usage_backup(service, alias, scheme, ports, unimplemented), + usage_docker_pull(service, alias, scheme, ports, unimplemented), ]) -def usage_intro(service, alias, scheme, ports): - return "\n".join([ - "### Basic Usage", - command_help("list", service, alias, scheme, ports), - command_help("create", service, alias, scheme, ports), - command_help("info", service, alias, scheme, ports), - command_help("logs", service, alias, scheme, ports), - command_help("link", service, alias, scheme, ports), - command_help("unlink", service, alias, scheme, ports), - command_help("destroy", service, alias, scheme, ports), - ]) +def usage_intro(service, alias, scheme, ports, unimplemented): + commands = ["create", "info", "list", "logs", "link", "unlink"] + content = ["### Basic Usage"] + + return fetch_commands_content(service, alias, scheme, ports, unimplemented, commands, content) -def usage_lifecycle(service, alias, scheme, ports): - return "\n".join([ +def usage_lifecycle(service, alias, scheme, ports, unimplemented): + commands = ["connect", "enter", "expose", "unexpose", "promote", "start", "stop", "restart", "upgrade"] + content = [ "### Service Lifecycle", "", "The lifecycle of each service can be managed through the following commands:", "", - command_help("connect", service, alias, scheme, ports), - command_help("enter", service, alias, scheme, ports), - command_help("expose", service, alias, scheme, ports), - command_help("unexpose", service, alias, scheme, ports), - command_help("promote", service, alias, scheme, ports), - command_help("restart", service, alias, scheme, ports), - command_help("start", service, alias, scheme, ports), - command_help("stop", service, alias, scheme, ports), - command_help("upgrade", service, alias, scheme, ports), - ]) + ] + + return fetch_commands_content(service, alias, scheme, ports, unimplemented, commands, content) -def usage_automation(service, alias, scheme, ports): - return "\n".join([ +def usage_automation(service, alias, scheme, ports, unimplemented): + commands = ["app-links", "clone", "exists", "linked", "links"] + content = [ "### Service Automation", "", "Service scripting can be executed using the following commands:", "", - command_help("app-links", service, alias, scheme, ports), - command_help("clone", service, alias, scheme, ports), - command_help("exists", service, alias, scheme, ports), - command_help("linked", service, alias, scheme, ports), - command_help("links", service, alias, scheme, ports), - ]) + ] + + return fetch_commands_content(service, alias, scheme, ports, unimplemented, commands, content) -def usage_data_management(service, alias, scheme, ports): - return "\n".join([ +def usage_data_management(service, alias, scheme, ports, unimplemented): + commands = ["import", "export"] + content = [ "### Data Management", "", "The underlying service data can be imported and exported with the following commands:", "", - command_help("import", service, alias, scheme, ports), - command_help("export", service, alias, scheme, ports), - ]) + ] + + return fetch_commands_content(service, alias, scheme, ports, unimplemented, commands, content) -def usage_backup(service, alias, scheme, ports): - return "\n".join([ +def usage_backup(service, alias, scheme, ports, unimplemented): + commands = ["backup-auth", "backup-deauth", "backup", "backup-set-encryption", "backup-unset-encryption", "backup-schedule", "backup-schedule-cat", "backup-unschedule",] + content = [ "### Backups", "", "Datastore backups are supported via AWS S3 and S3 compatible services like [minio](https://github.com/minio/minio).", @@ -147,18 +148,12 @@ def usage_backup(service, alias, scheme, ports): "", "Backups can be performed using the backup commands:", "", - command_help("backup-auth", service, alias, scheme, ports), - command_help("backup-deauth", service, alias, scheme, ports), - command_help("backup", service, alias, scheme, ports), - command_help("backup-set-encryption", service, alias, scheme, ports), - command_help("backup-unset-encryption", service, alias, scheme, ports), - command_help("backup-schedule", service, alias, scheme, ports), - command_help("backup-schedule-cat", service, alias, scheme, ports), - command_help("backup-unschedule", service, alias, scheme, ports), - ]) + ] + + return fetch_commands_content(service, alias, scheme, ports, unimplemented, commands, content) -def usage_docker_pull(service, alias, scheme, ports): +def usage_docker_pull(service, alias, scheme, ports, unimplemented): service_prefix = service.upper() return "\n".join([ "### Disabling `docker pull` calls", @@ -169,6 +164,21 @@ def usage_docker_pull(service, alias, scheme, ports): ]) +def fetch_commands_content(service, alias, scheme, ports, unimplemented, commands, content): + i = 0 + for command in commands: + output = command_help(command, service, alias, scheme, ports, unimplemented) + if output == "": + continue + content.append(output) + i += 1 + + if i == 0: + return "" + + return "\n".join(content) + + def parse_args(line): line = line.strip() arguments = [] @@ -195,7 +205,10 @@ def parse_args(line): return " ".join(arguments) -def command_help(command, service, alias, scheme, ports): +def command_help(command, service, alias, scheme, ports, unimplemented): + if command in unimplemented: + return "" + data = command_data(command, service, alias, scheme, ports) content = [ f"### {data['description']}", @@ -221,12 +234,10 @@ def command_help(command, service, alias, scheme, ports): # content.append(f"- {flag}") if len(data["examples"]) > 0: - content.append("") - content.append("examples:") content.append("") content.append(data["examples"]) - return "\n".join(content) + return "\n" + "\n".join(content) def command_data(command, service, alias, scheme, ports): @@ -339,7 +350,7 @@ def command_data(command, service, alias, scheme, ports): def process_sentence(sentence_lines): sentence_lines = " ".join(sentence_lines) - sentences = ". ".join(i.strip().capitalize() for i in sentence_lines.split(".")) + sentences = ". ".join(i.strip().capitalize() for i in sentence_lines.split(".")).strip() if not sentences.endswith(".") and not sentences.endswith(":"): sentences += ":" return sentences @@ -359,21 +370,11 @@ def process_codeblock(codeblock_lines): return f"```\n{codeblock_lines}\n```" -def compile(service, version, alias, scheme, ports, dokku_version): - return "\n\n".join([ - header(service), - description(service, version), - requirements(dokku_version), - installation(service, dokku_version), - commands(service, alias, scheme, ports), - usage(service, alias, scheme, ports), - ]) - - def main(): service = None version = None alias = None + unimplemented = [] with open("config") as f: for line in f.readlines(): if "IMAGE_VERSION=${" in line: @@ -386,8 +387,12 @@ def main(): scheme = re.search('"(.+)"', line).group(1) if "PLUGIN_DATASTORE_PORTS=" in line: ports = re.search('\((.+)\)', line).group(1).split(" ") + if "PLUGIN_UNIMPLEMENTED_SUBCOMMANDS=" in line: + match = re.search('\((.+)\)', line) + if match is not None: + unimplemented = [s.strip('"') for s in match.group(1).split(" ")] - text = compile(service, version, alias, scheme, ports, "0.12.x+") + text = compile(service, version, alias, scheme, ports, unimplemented, "0.12.x+") base_path = os.path.dirname(os.path.dirname(os.path.realpath(__file__))) readme_file = os.path.join(base_path, 'README.md') diff --git a/subcommands/info b/subcommands/info index 21dfd4a..6aca3f1 100755 --- a/subcommands/info +++ b/subcommands/info @@ -30,7 +30,7 @@ service-info-cmd() { #F --service-root, show the service root directory #F --status, show the service running status #F --version, show the service image version - declare desc="print the connection information" + declare desc="print the service information" local cmd="$PLUGIN_COMMAND_PREFIX:info" argv=("$@") [[ ${argv[0]} == "$cmd" ]] && shift 1 declare SERVICE="$1" INFO_FLAG="$2"