From 29847b7ab67dd487ecc1e69b358f413cd7d7983b Mon Sep 17 00:00:00 2001 From: Jose Diaz-Gonzalez Date: Tue, 5 Jul 2016 01:11:18 -0400 Subject: [PATCH 1/5] Separate application management docs Also add complete documentation around all the commands in the apps plugin. --- docs/deployment/application-deployment.md | 38 ++------ docs/deployment/application-management.md | 110 ++++++++++++++++++++++ docs/template.html | 1 + 3 files changed, 119 insertions(+), 30 deletions(-) create mode 100644 docs/deployment/application-management.md diff --git a/docs/deployment/application-deployment.md b/docs/deployment/application-deployment.md index 7babf2e8c..1121592f0 100644 --- a/docs/deployment/application-deployment.md +++ b/docs/deployment/application-deployment.md @@ -85,36 +85,6 @@ When the deploy finishes, the application's URL will be shown as seen above. Dokku supports deploying applications via [Heroku buildpacks](https://devcenter.heroku.com/articles/buildpacks) with [Herokuish](https://github.com/gliderlabs/herokuish#buildpacks) or using a project's [dockerfile](https://docs.docker.com/reference/builder/). -### Removing a deployed app - -You can also remove an application from your Dokku installation. This will unlink all linked services and destroy any config related to the application. Note that linked services will retain their data for later use (or removal). - -```shell -# on your dokku host -# replace APP with the name of your application -dokku apps:destroy APP -``` - -This will prompt you to verify the application's name before destroying it. You may also use the `--force` flag to circumvent this verification process: - -```shell -# on your dokku host -# replace APP with the name of your application -dokku --force apps:destroy APP -``` - -### Renaming a deployed app - -> New as of 0.4.7 - -You can rename a deployed app using the `apps:rename` CLI tool: - -```shell -# on your dokku host -dokku apps:rename OLD_NAME NEW_NAME -``` - -This will copy all of your app's contents into a new app directory with the name of your choice, delete your old app, then rebuild the new version of the app and deploy it. All of your config variables, including database urls, will be preserved. ### Deploying non-master branch @@ -208,6 +178,14 @@ See the [buildpack documentation](/dokku/deployment/buildpacks/). See the [image tagging documentation](/dokku/deployment/images/). +## Removing a deployed app + +See the [application management documentation](/dokku/deployment/application-management/#removing-a-deployed-app). + +### Renaming a deployed app + +See the [application management documentation](/dokku/deployment/application-management/#renaming-a-deployed-app). + ## Zero downtime deploy See the [zero-downtime deploy documentation](/dokku/deployment/zero-downtime-deploys/). diff --git a/docs/deployment/application-management.md b/docs/deployment/application-management.md new file mode 100644 index 000000000..d60864d5c --- /dev/null +++ b/docs/deployment/application-management.md @@ -0,0 +1,110 @@ +# Application Management + +> New as of 0.3.1 + +``` +apps # List your apps +apps:create # Create a new app +apps:destroy # Permanently destroy an app +apps:rename # Rename an app +``` + +You can easily list all available applications using the `apps` command: + +```shell +dokku apps +``` + +``` +=====> My Apps +node-js-sample +python-sample +``` + +Note that you can easily hide extra output from dokku commands by using the `--quiet` flag, which makes it easier to parse on the command-line. + +```shell +dokku --quiet apps +``` + +``` +node-js-sample +python-sample +``` + +## Manually creating an application + +A common pattern for deploying applications to Dokku is to configure an application before deploying it. You can do so via the `apps:create` command: + +```shell +dokku apps:create node-js-app +``` + +``` +Creating node-js-app... done +``` + +Once created, you can configure the application as normal, and deploy the application whenever ready. This is useful for cases where you may wish to do any of the following kinds of tasks: + +- configure domain names and ssl certificates +- create and link datastores +- set environment variables + +## Removing a deployed app + +In some cases, you may need to destroy an application, whether it is because the application is temporary or because it was misconfigured. In these cases, you can use the `apps:destroy` command. Performing any destructive actions in Dokku requires confirmation, and this command will ask for the name of the application being deleted before doing so. + +```shell +dokku apps:destroy node-js-app +``` + +``` + ! WARNING: Potentially Destructive Action + ! This command will destroy node-js-app (including all add-ons). + ! To proceed, type "node-js-app" + +> node-js-app +Destroying node-js-app (including all add-ons) +``` + +This will prompt you to verify the application's name before destroying it. You may also use the `--force` flag to circumvent this verification process: + +```shell +dokku --force apps:destroy node-js-app +``` + +``` +Destroying node-js-app (including all add-ons) +``` + + +Destroying an application will unlink all linked services and destroy any config related to the application. Note that linked services will retain their data for later use (or removal). + +## Renaming a deployed app + +> New as of 0.4.7 + +You can rename a deployed app using the `apps:rename` command. Note that the application *must* have been deployed at least once, or the rename will not complete successfully: + +```shell +dokku apps:rename node-js-app io-js-app +``` + +``` +Destroying node-js-app (including all add-ons) +-----> Cleaning up... +-----> Building io-js-app from herokuish... +-----> Adding BUILD_ENV to build environment... +-----> Node.js app detected + +-----> Creating runtime environment + +... + +=====> Application deployed: + http://io-js-app.ci.dokku.me + +Renaming node-js-app to io-js-app... done +``` + +This will copy all of your app's contents into a new app directory with the name of your choice, delete your old app, then rebuild the new version of the app and deploy it. All of your config variables, including database urls, will be preserved. diff --git a/docs/template.html b/docs/template.html index 652d3b51b..22790da1f 100644 --- a/docs/template.html +++ b/docs/template.html @@ -134,6 +134,7 @@ Buildpack Deployment Dockerfile Deployment Image Tagging + Application Management Remote Commands One Off Processes/Cron Scaling Apps From 35947100b85423cee78877b62cfb799f4db496cd Mon Sep 17 00:00:00 2001 From: Jose Diaz-Gonzalez Date: Tue, 5 Jul 2016 01:16:14 -0400 Subject: [PATCH 2/5] Move all deployment methods into their own section This makes our support for each method explicit, and also allows us to add more deployment methods in the future. [ci skip] --- docs/appendices/0.5.0-migration-guide.md | 2 +- docs/deployment/application-deployment.md | 6 +++--- docs/deployment/{ => methods}/buildpacks.md | 0 docs/deployment/{ => methods}/dockerfiles.md | 0 docs/deployment/{ => methods}/images.md | 2 +- docs/template.html | 9 ++++++--- docs/viewdocs.json | 3 +++ 7 files changed, 14 insertions(+), 8 deletions(-) rename docs/deployment/{ => methods}/buildpacks.md (100%) rename docs/deployment/{ => methods}/dockerfiles.md (100%) rename docs/deployment/{ => methods}/images.md (99%) diff --git a/docs/appendices/0.5.0-migration-guide.md b/docs/appendices/0.5.0-migration-guide.md index 58f1d1424..e8a606e65 100644 --- a/docs/appendices/0.5.0-migration-guide.md +++ b/docs/appendices/0.5.0-migration-guide.md @@ -20,6 +20,6 @@ ## Dockerfile apps with exposed ports -- Dockerfiles with `EXPOSE` clauses will get [all **tcp** ports proxied by default](/dokku/deployment/dockerfiles/#exposed-ports) +- Dockerfiles with `EXPOSE` clauses will get [all **tcp** ports proxied by default](/dokku/deployment/methods/dockerfiles/#exposed-ports) - Note that nginx will proxy the same port numbers to listen publicly - UDP ports can be exposed by disabling the [nginx proxy](/dokku/advanced-usage/proxy-management/) with `dokku proxy:disable myapp` diff --git a/docs/deployment/application-deployment.md b/docs/deployment/application-deployment.md index 1121592f0..841bd6e50 100644 --- a/docs/deployment/application-deployment.md +++ b/docs/deployment/application-deployment.md @@ -168,15 +168,15 @@ See the [nginx documentation](/dokku/configuration/nginx/#default-site). ## Dockerfile deployment -See the [dockerfile documentation](/dokku/deployment/dockerfiles/). +See the [dockerfile documentation](/dokku/deployment/methods/dockerfiles/). ## Specifying a custom buildpack -See the [buildpack documentation](/dokku/deployment/buildpacks/). +See the [buildpack documentation](/dokku/deployment/methods/buildpacks/). ## Image tagging -See the [image tagging documentation](/dokku/deployment/images/). +See the [image tagging documentation](/dokku/deployment/methods/images/). ## Removing a deployed app diff --git a/docs/deployment/buildpacks.md b/docs/deployment/methods/buildpacks.md similarity index 100% rename from docs/deployment/buildpacks.md rename to docs/deployment/methods/buildpacks.md diff --git a/docs/deployment/dockerfiles.md b/docs/deployment/methods/dockerfiles.md similarity index 100% rename from docs/deployment/dockerfiles.md rename to docs/deployment/methods/dockerfiles.md diff --git a/docs/deployment/images.md b/docs/deployment/methods/images.md similarity index 99% rename from docs/deployment/images.md rename to docs/deployment/methods/images.md index 6bd3d4b8c..f5e0badce 100644 --- a/docs/deployment/images.md +++ b/docs/deployment/methods/images.md @@ -1,4 +1,4 @@ -# Image Tagging +# Image Tag Deployment > New as of 0.4.0 diff --git a/docs/template.html b/docs/template.html index 22790da1f..c1284301b 100644 --- a/docs/template.html +++ b/docs/template.html @@ -131,9 +131,6 @@ Deployment Deploying an Application - Buildpack Deployment - Dockerfile Deployment - Image Tagging Application Management Remote Commands One Off Processes/Cron @@ -141,6 +138,12 @@ User Management Zero Downtime Deploy Checks + Deployment Methods + + Buildpack Deployment + Dockerfile Deployment + Docker Image Deployment + Configuration Environment Variables diff --git a/docs/viewdocs.json b/docs/viewdocs.json index f7b28ff41..353ae1703 100644 --- a/docs/viewdocs.json +++ b/docs/viewdocs.json @@ -9,6 +9,9 @@ "process-management": "deployment/process-management/", "remote-commands": "deployment/remote-commands/", + "deployment/buildpacks": "deployment/methods/buildpacks/", + "deployment/dockerfiles": "deployment/methods/dockerfiles/", + "deployment/images": "deployment/methods/images/", "configuration-management": "configuration/environment-variables/", "deployment/ssl-configuration": "configuration/ssl/", "dns": "configuration/dns/", From 3ae6b3f1a8314ba3231c741279a78f28f4b18db3 Mon Sep 17 00:00:00 2001 From: Jose Diaz-Gonzalez Date: Tue, 5 Jul 2016 01:16:57 -0400 Subject: [PATCH 3/5] Document tar deployment method [ci skip] --- docs/deployment/methods/tar.md | 25 +++++++++++++++++++++++++ docs/template.html | 1 + plugins/tar/commands | 1 - 3 files changed, 26 insertions(+), 1 deletion(-) create mode 100644 docs/deployment/methods/tar.md diff --git a/docs/deployment/methods/tar.md b/docs/deployment/methods/tar.md new file mode 100644 index 000000000..a32e1c09e --- /dev/null +++ b/docs/deployment/methods/tar.md @@ -0,0 +1,25 @@ +# Tarfile Deployment + +> New as of 0.4.0 + +``` +tar:from # Loads an app tarball from url +tar:in # Reads an tarball containing the app from stdin +``` + +## Deploying from a tarball + +In some cases, it may be useful to deploy an application from a tarball. For instance, if you implemented a non-git based deployment plugin, tarring the generated artifact may be an easier route to interface with the existing dokku infrastructure. + +You can place the tarball on an external webserver and deploy via the `tar:from` command. + +```shell +dokku tar:from node-js-app https://dokku.me/releases/node-js-app/v1 +``` + +As an alternative, a deploy can be trigged from a tarball read from stdin using the `tar:in` command: + +```shell +# run from the generated artifact directory +tar c . $* | dokku tar:in node-js-app +``` diff --git a/docs/template.html b/docs/template.html index c1284301b..f98fb94b6 100644 --- a/docs/template.html +++ b/docs/template.html @@ -143,6 +143,7 @@ Buildpack Deployment Dockerfile Deployment Docker Image Deployment + Tarfile Deployment Configuration diff --git a/plugins/tar/commands b/plugins/tar/commands index ce4db88f9..60a8123a5 100755 --- a/plugins/tar/commands +++ b/plugins/tar/commands @@ -7,7 +7,6 @@ case "$1" in help_content_func () { declare desc="return tar plugin help content" cat<, Reads an tarball containing the app from stdin tar:from , Loads an app tarball from url help_content From c940b7f979da0e6b41ee9cbe7c345d4136d30c4d Mon Sep 17 00:00:00 2001 From: Jose Diaz-Gonzalez Date: Tue, 5 Jul 2016 01:17:58 -0400 Subject: [PATCH 4/5] Document the repo plugin [ci skip] --- docs/advanced-usage/repository-management.md | 34 ++++++++++++++++++++ docs/deployment/methods/buildpacks.md | 13 +++----- docs/template.html | 1 + 3 files changed, 39 insertions(+), 9 deletions(-) create mode 100644 docs/advanced-usage/repository-management.md diff --git a/docs/advanced-usage/repository-management.md b/docs/advanced-usage/repository-management.md new file mode 100644 index 000000000..936eceb34 --- /dev/null +++ b/docs/advanced-usage/repository-management.md @@ -0,0 +1,34 @@ +# Repository Management + +> New as of 0.6.0 + +``` +repo:gc # Runs 'git gc --agressive' against the application's repo +repo:purge-cache # Deletes the contents of the build cache stored in the repository +``` + +The repository plugin is meant to allow users to perform management commands against a repository. + +# Git Garbage Collection + +This will run a git gc --agressive against the applications repo. This is performed on the Dokku host, and not within an application container. + +```shell +dokku repo:gc node-js-app +``` + +``` +Counting objects: 396, done. +Delta compression using up to 2 threads. +Compressing objects: 100% (365/365), done. +Writing objects: 100% (396/396), done. +Total 396 (delta 79), reused 315 (delta 0) +``` + +## Clearing Application cache + +Building containers with buildpacks currently results in a persistent `cache` directory between deploys. If you need to clear this cache directory for any reason, you may do so by running the following shell command: + +```shell +dokku repo:purge-cache node-js-app +``` diff --git a/docs/deployment/methods/buildpacks.md b/docs/deployment/methods/buildpacks.md index 44130b2c3..f6d38782f 100644 --- a/docs/deployment/methods/buildpacks.md +++ b/docs/deployment/methods/buildpacks.md @@ -82,15 +82,6 @@ importantworker: env QUEUE=important bundle exec rake resque:work The `web` process type holds some significance in that it is the only process type that is automatically scaled to `1` on the initial application deploy. See the [process scaling documentation](/dokku/deployment/process-management/) for more details around scaling individual processes. -## Clearing buildpack cache - -Building containers with buildpacks currently results in a persistent `cache` directory between deploys. If you need to clear this cache directory for any reason, you may do so by running the following shell command: - -```shell -# replace APP with the name of your application -sudo rm -rf /home/dokku/APP/cache/* -``` - ## Curl Build Timeouts Certain buildpacks may time out in retrieving dependencies via curl. This can happen when your network connection is poor or if there is significant network congestion. You may see a message similar to `gzip: stdin: unexpected end of file` after a curl command. @@ -101,3 +92,7 @@ If you see output similar this when deploying , you may need to override the cur dokku config:set --global CURL_TIMEOUT=600 dokku config:set --global CURL_CONNECT_TIMEOUT=30 ``` + +## Clearing buildpack cache + +See the [repository management documentation](/dokku/advanced-usage/repository-management/#clearing-app-cache). diff --git a/docs/template.html b/docs/template.html index f98fb94b6..6061f9ec7 100644 --- a/docs/template.html +++ b/docs/template.html @@ -161,6 +161,7 @@ Event Logs Persistent Storage Proxy Management + Repository Management Community Contributions From 7848ab2a8c38b911b4c2501cacf7d8610e994b08 Mon Sep 17 00:00:00 2001 From: Jose Diaz-Gonzalez Date: Tue, 5 Jul 2016 01:18:31 -0400 Subject: [PATCH 5/5] Add hashes to beginning of commands in more plugins [ci skip] --- docs/deployment/one-off-processes.md | 4 ++-- docs/deployment/user-management.md | 8 ++++---- docs/deployment/zero-downtime-deploys.md | 8 ++++---- 3 files changed, 10 insertions(+), 10 deletions(-) diff --git a/docs/deployment/one-off-processes.md b/docs/deployment/one-off-processes.md index dac0cedc0..c6e3dbb3a 100644 --- a/docs/deployment/one-off-processes.md +++ b/docs/deployment/one-off-processes.md @@ -5,7 +5,7 @@ Sometimes you need to either inspect running containers or run a one-off command ## Run a command in an app environment ``` -run Run a command in the environment of an application +run # Run a command in the environment of an application ``` The `run` command can be used to run a one-off process for a specific command. This will start a new container and run the desired command within that container. Note that this container will be stay around even after command completes. The container will be the same container as was used to start the currently deployed application. @@ -68,7 +68,7 @@ For tasks that should not be interrupted, run is the **preferred** method of han > New as of 0.4.0 ``` -enter [ || --container-id ] Connect to a specific app container +enter [ || --container-id ] # Connect to a specific app container ``` The `enter` command can be used to enter a running container. The following variations of the command exist: diff --git a/docs/deployment/user-management.md b/docs/deployment/user-management.md index 0c6cd4eb1..1eaaa7459 100644 --- a/docs/deployment/user-management.md +++ b/docs/deployment/user-management.md @@ -9,10 +9,10 @@ Users in dokku are managed via the `~/dokku/.ssh/authorized_keys` file. While yo Dokku uses the [`sshcommand`](https://github.com/dokku/sshcommand) utility to manage ssh keys for the dokku user. The following is the usage output for sshcommand. ``` -sshcommand create # creates a user forced to run command when SSH connects -sshcommand acl-add # adds named SSH key to user from STDIN -sshcommand acl-remove # removes SSH key by name -sshcommand help # displays the usage help message +sshcommand create # creates a user forced to run command when SSH connects +sshcommand acl-add # adds named SSH key to user from STDIN +sshcommand acl-remove # removes SSH key by name +sshcommand help # displays the usage help message ``` In dokku's case, the `` section is *always* `dokku`, as this is the system user that the dokku binary performs all it's actions. Keys are given unique names, which can be used in conjunction with the [user-auth](/dokku/development/plugin-triggers/#user-auth) plugin trigger to handle command authorization. diff --git a/docs/deployment/zero-downtime-deploys.md b/docs/deployment/zero-downtime-deploys.md index 9d97385eb..b97c7b269 100644 --- a/docs/deployment/zero-downtime-deploys.md +++ b/docs/deployment/zero-downtime-deploys.md @@ -3,10 +3,10 @@ > New as of 0.5.0 ``` -checks # Show zero-downtime status -checks:disable [process-type(s)] # Disable zero-downtime deployment for all processes (or comma-separated process-type list) ***WARNING: this will cause downtime during deployments*** -checks:enable [process-type(s)] # Enable zero-downtime deployment for all processes (or comma-separated process-type list) -checks:skip [process-type(s)] # Skip zero-downtime checks for all processes (or comma-separated process-type list) +checks # Show zero-downtime status +checks:disable [process-type(s)] # Disable zero-downtime deployment for all processes (or comma-separated process-type list) ***WARNING: this will cause downtime during deployments*** +checks:enable [process-type(s)] # Enable zero-downtime deployment for all processes (or comma-separated process-type list) +checks:skip [process-type(s)] # Skip zero-downtime checks for all processes (or comma-separated process-type list) ``` Following a deploy, dokku will wait `10` seconds before routing traffic to the new container to give your application time to boot up. If the application is not running after this time, then the deploy is failed and your old container will continue serving traffic. You can modify this value globally or on a per-application basis: