From 9951a16ccce7b8475ad5dd77602af7b212b3a742 Mon Sep 17 00:00:00 2001 From: Jose Diaz-Gonzalez Date: Sun, 20 Nov 2016 15:37:05 -0700 Subject: [PATCH 1/5] docs: standardize on node-js-app as the app name MIME-Version: 1.0 Content-Type: text/plain; charset=UTF-8 Content-Transfer-Encoding: 8bit We’ll probably want to update this to whatever the hip language of the day is, but for now, having the same reference everywhere works. --- docs/configuration/ssl.md | 3 +-- docs/deployment/methods/buildpacks.md | 11 ++++------- docs/deployment/methods/dockerfiles.md | 2 +- docs/deployment/zero-downtime-deploys.md | 14 +++++++------- docs/development/plugin-creation.md | 4 ++-- docs/getting-started/upgrading.md | 4 ++-- 6 files changed, 17 insertions(+), 21 deletions(-) diff --git a/docs/configuration/ssl.md b/docs/configuration/ssl.md index 7a1a397d8..8656606c6 100644 --- a/docs/configuration/ssl.md +++ b/docs/configuration/ssl.md @@ -29,8 +29,7 @@ The `certs:add` command can be used to push a `tar` containing a certificate `.c ```shell tar cvf cert-key.tar server.crt server.key -# replace APP with the name of your application -dokku certs:add < cert-key.tar +dokku certs:add node-js-app < cert-key.tar ``` > Note: If your `.crt` file came alongside a `.ca-bundle`, you'll want to concatenate those into a single `.crt` file before adding it to the `.tar`. diff --git a/docs/deployment/methods/buildpacks.md b/docs/deployment/methods/buildpacks.md index 897d9ef41..79f1bc2d4 100644 --- a/docs/deployment/methods/buildpacks.md +++ b/docs/deployment/methods/buildpacks.md @@ -14,12 +14,11 @@ In certain cases you may want to specify a custom buildpack. While Dokku uses he To use a specific buildpack, you can run the following Dokku command: ```shell -# replace APP with the name of your application # replace REPOSITORY_URL with your buildpack's url -dokku config:set APP BUILDPACK_URL=REPOSITORY_URL +dokku config:set node-js-app BUILDPACK_URL=REPOSITORY_URL # example: using a specific ruby buildpack version -dokku config:set APP BUILDPACK_URL=https://github.com/heroku/heroku-buildpack-ruby.git#v142 +dokku config:set node-js-app BUILDPACK_URL=https://github.com/heroku/heroku-buildpack-ruby.git#v142 ``` Please check the documentation for your particular buildpack as you may need to include configuration files (such as a Procfile) in your project root. @@ -45,16 +44,14 @@ As Dokku pins all buildpacks via herokuish releases, there may be occasions wher ```shell # using the latest nodejs buildpack -# replace APP with the name of your application -dokku config:set APP BUILDPACK_URL=https://github.com/heroku/heroku-buildpack-nodejs +dokku config:set node-js-app BUILDPACK_URL=https://github.com/heroku/heroku-buildpack-nodejs ``` You may also wish to use a **specific** version of a buildpack, which is also simple ```shell # using v87 of the nodejs buildpack -# replace APP with the name of your application -dokku config:set APP BUILDPACK_URL=https://github.com/heroku/heroku-buildpack-nodejs#v87 +dokku config:set node-js-app BUILDPACK_URL=https://github.com/heroku/heroku-buildpack-nodejs#v87 ``` ## Specifying commands via Procfile diff --git a/docs/deployment/methods/dockerfiles.md b/docs/deployment/methods/dockerfiles.md index a51b427da..ebc91f65b 100644 --- a/docs/deployment/methods/dockerfiles.md +++ b/docs/deployment/methods/dockerfiles.md @@ -34,7 +34,7 @@ ENTRYPOINT ["node"] You can do: ```shell -dokku config:set APP DOKKU_DOCKERFILE_START_CMD="--harmony server.js" +dokku config:set node-js-app DOKKU_DOCKERFILE_START_CMD="--harmony server.js" ``` To tell docker what to run. diff --git a/docs/deployment/zero-downtime-deploys.md b/docs/deployment/zero-downtime-deploys.md index 2ef6bd89e..a2ff6db3d 100644 --- a/docs/deployment/zero-downtime-deploys.md +++ b/docs/deployment/zero-downtime-deploys.md @@ -52,7 +52,7 @@ Dokku will wait `60` seconds before stopping the old container so that existing ```shell dokku config:set --global DOKKU_WAIT_TO_RETIRE=120 -dokku config:set DOKKU_WAIT_TO_RETIRE=120 +dokku config:set node-js-app DOKKU_WAIT_TO_RETIRE=120 ``` > Note that during this time, multiple containers may be running on your server, which can be an issue for memory-hungry applications on memory-constrained servers. @@ -92,7 +92,7 @@ dokku checks:run APP Checks can be scoped to a particular process type: ```shell -dokku checks:run APP worker +dokku checks:run node-js-app worker ``` ``` @@ -108,7 +108,7 @@ dokku checks:run APP worker An app process id may also be specified: ```shell -dokku checks:run APP web.2 +dokku checks:run node-js-app web.2 ``` ``` @@ -124,7 +124,7 @@ dokku checks:run APP web.2 Non-existent process types will result in an error: ```shell -dokku checks:run APP non-existent +dokku checks:run node-js-app non-existent ``` ``` @@ -135,7 +135,7 @@ Invalid process type specified (APP.non-existent) Non-existent process ids will *also* result in an error ```shell -dokku checks:run APP web.3 +dokku checks:run node-js-app web.3 ``` ``` @@ -214,7 +214,7 @@ dokku config:set --global DOKKU_CHECKS_ATTEMPTS=10 If your application runs multiple processes (a background worker configured in your `Procfile`, for example) and you have checks to ensure that your web application has booted up, you may want to disable the default check wait time for that application to avoid the `10` second wait per non-web process: ```shell -dokku config:set DOKKU_DEFAULT_CHECKS_WAIT=0 +dokku config:set node-js-app DOKKU_DEFAULT_CHECKS_WAIT=0 ``` ### Configuring docker stop timeout @@ -222,7 +222,7 @@ dokku config:set DOKKU_DEFAULT_CHECKS_WAIT=0 [By default](https://docs.docker.com/engine/reference/commandline/stop/), docker will wait 10 seconds from the time the `stop` command is passed to a container before it attempts to kill said container. This timeout can be configured on a per-app basis in Dokku by setting the `DOKKU_DOCKER_STOP_TIMEOUT` configuration variable. This timeout applies to normal zero-downtime deployments as well as the `ps:stop` and `apps:destroy` commands. ```shell -dokku config:set $APP DOKKU_DOCKER_STOP_TIMEOUT=20 +dokku config:set node-js-app DOKKU_DOCKER_STOP_TIMEOUT=20 ``` ## Example: Successful Rails Deployment diff --git a/docs/development/plugin-creation.md b/docs/development/plugin-creation.md index 3c7bff94a..2a2134082 100644 --- a/docs/development/plugin-creation.md +++ b/docs/development/plugin-creation.md @@ -150,8 +150,8 @@ A few notes: - As some plugins require access to set app config settings and do not want/require the default Heroku-style behavior of a restart, we have the following "internal" commands that provide this functionality : ```shell - dokku config:set --no-restart APP KEY1=VALUE1 [KEY2=VALUE2 ...] - dokku config:unset --no-restart APP KEY1 [KEY2 ...] + dokku config:set --no-restart node-js-app KEY1=VALUE1 [KEY2=VALUE2 ...] + dokku config:unset --no-restart node-js-app KEY1 [KEY2 ...] ``` - From time to time you may want to allow other plugins access to (some of) your plugin's functionality. You can expose this by including a `functions` file in your plugin for others to source. Consider all functions in that file to be publicly accessible by other plugins. Any functions not wished to be made "public" should reside within your plugin trigger or commands files. - As of 0.4.0, we allow image tagging and deployment of said tagged images. Therefore, hard-coding of `$IMAGE` as `dokku/$APP` is no longer sufficient. Instead, for non `pre/post-build-*` plugins, use `get_running_image_tag()` & `get_app_image_name()` as sourced from common/functions. See the [plugin triggers](/dokku/development/plugin-triggers) doc for examples. diff --git a/docs/getting-started/upgrading.md b/docs/getting-started/upgrading.md index 42cfa36a6..667d668e4 100644 --- a/docs/getting-started/upgrading.md +++ b/docs/getting-started/upgrading.md @@ -25,7 +25,7 @@ If Dokku was installed via `apt-get install dokku` or `bootstrap.sh` (most commo ```shell sudo apt-get update dokku apps -dokku ps:stop # repeat to shut down each running app +dokku ps:stop APP # repeat to shut down each running app sudo apt-get install -qq -y dokku herokuish dokku ps:rebuildall # rebuilds all applications ``` @@ -46,7 +46,7 @@ If you installed Dokku from source (less common), upgrade with: ```shell dokku apps -dokku ps:stop # repeat to shut down each running app +dokku ps:stop APP # repeat to shut down each running app cd ~/dokku git pull --tags origin master From 95239a57310323835763a96c9552510585edd942 Mon Sep 17 00:00:00 2001 From: Jose Diaz-Gonzalez Date: Sun, 20 Nov 2016 15:37:21 -0700 Subject: [PATCH 2/5] docs: remove unnecessary example --- docs/deployment/logs.md | 7 +------ 1 file changed, 1 insertion(+), 6 deletions(-) diff --git a/docs/deployment/logs.md b/docs/deployment/logs.md index 9be0352f8..eefb5983c 100644 --- a/docs/deployment/logs.md +++ b/docs/deployment/logs.md @@ -24,13 +24,8 @@ Dokku also supports certain command-line arguments that augment the `log` comman -q, --quiet # display raw logs without colors, time and names ``` -You can use these modifiers as +You can use these modifiers as follows: -```shell -dokku logs -``` - -For example, ```shell dokku logs node-js-app -t -p web From f6c072fa2b0bb768d5dcaef122561b331a7e5311 Mon Sep 17 00:00:00 2001 From: Jose Diaz-Gonzalez Date: Sun, 20 Nov 2016 15:38:01 -0700 Subject: [PATCH 3/5] docs: remove extra output --- docs/advanced-usage/plugin-management.md | 11 ----------- 1 file changed, 11 deletions(-) diff --git a/docs/advanced-usage/plugin-management.md b/docs/advanced-usage/plugin-management.md index 985b386ae..01af0b16b 100644 --- a/docs/advanced-usage/plugin-management.md +++ b/docs/advanced-usage/plugin-management.md @@ -72,17 +72,6 @@ Receiving objects: 100% (646/646), 134.24 KiB | 0 bytes/s, done. Resolving deltas: 100% (406/406), done. Checking connectivity... done. -----> Plugin postgres enabled ------> Migrating zero downtime env variables to 0.5.x. The following variables have been deprecated -=====> DOKKU_SKIP_ALL_CHECKS DOKKU_SKIP_DEFAULT_CHECKS -=====> Please use dokku checks:[disable|enable] to control zero downtime functionality -=====> Migration complete -=====> ------> Migrating zero downtime env variables to 0.6.x. The following variables will be migrated -=====> DOKKU_CHECKS_ENABLED -> DOKKU_CHECKS_SKIPPED -=====> Migration complete -=====> -Adding user dokku to group adm -Starting nginx (via systemctl): nginx.service. ``` You can also uninstall a third-party plugin using the `plugin:uninstall` command: From d7bc6976ed73ac782ed872b0c734cad65eb3897c Mon Sep 17 00:00:00 2001 From: Jose Diaz-Gonzalez Date: Sun, 20 Nov 2016 16:07:05 -0700 Subject: [PATCH 4/5] docs: Mention that ports are ignored in CHECKS doc Closes #2487 [ci skip] --- docs/deployment/zero-downtime-deploys.md | 2 ++ 1 file changed, 2 insertions(+) diff --git a/docs/deployment/zero-downtime-deploys.md b/docs/deployment/zero-downtime-deploys.md index a2ff6db3d..0a502ce37 100644 --- a/docs/deployment/zero-downtime-deploys.md +++ b/docs/deployment/zero-downtime-deploys.md @@ -189,6 +189,8 @@ https://admin.example.com Admin Dashboard https://static.example.com/logo.png ``` +While a full url may be used in order to invoke checks, if you are using relative urls, the port *must* be omitted. + ### Check Settings The default behavior is to wait for `5` seconds before running the checks, to timeout the checks after `30` seconds, and to attempt the checks `5` times. If the checks fail `5` times, the deployment is considered failed and the old container will continue serving traffic. From 8d6f32e1e34d61e1d9cccceb824682f36585c66d Mon Sep 17 00:00:00 2001 From: Jose Diaz-Gonzalez Date: Sun, 20 Nov 2016 16:12:26 -0700 Subject: [PATCH 5/5] docs: reword zero downtime docs to make them flow better [ci skip] --- docs/deployment/zero-downtime-deploys.md | 184 ++++++++++------------- 1 file changed, 83 insertions(+), 101 deletions(-) diff --git a/docs/deployment/zero-downtime-deploys.md b/docs/deployment/zero-downtime-deploys.md index 0a502ce37..c1b24c9d5 100644 --- a/docs/deployment/zero-downtime-deploys.md +++ b/docs/deployment/zero-downtime-deploys.md @@ -10,18 +10,32 @@ checks:run [process-type(s)] Runs zero-downtime checks for all proce 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: - -```shell -dokku config:set --global DOKKU_DEFAULT_CHECKS_WAIT=30 -dokku config:set node-js-app DOKKU_DEFAULT_CHECKS_WAIT=30 -``` - -You can also choose to skip checks or disable zero-downtime completely on a per-application/per-process basis - -> Note that `checks:disable` will now (as of 0.6.0) cause downtime for that process-type during deployments. +By default, Dokku will wait `10` seconds after starting each container before assuming it is up and proceeding with the deploy. Once this has occurred for all containers started by for an application, traffic will be switched to point to your new containers. Dokku will also wait a further `60` seconds _after_ the deploy is complete before terminating old containers in order to give time for long running connections to terminate. In either case, you may have more than one container running for a given application. + +You may both create user-defined checks for web processes using a `CHECKS` file, as well as customize any and all parts of this experience using the checks plugin. + +## Configuring Check Settings using the `config` plugin + +There are certain settings that can be configured via environment variables: + +- `DOKKU_DEFAULT_CHECKS_WAIT`: (default: `10`) If no user-defined checks are specified - or if the process being checked is not a `web` process - this is the period of time Dokku will wait before checking that a container is still running. +- `DOKKU_DOCKER_STOP_TIMEOUT`: (default: `10`) Configurable grace period given to the `docker stop` command. If a container has not stopped by this time, a `kill -9` signal or equivalent is sent in order to force-terminate the container. Both the `ps:stop` and `apps:destroy` commands _also_ respect this value. If not specified, the docker defaults for the [docker stop command](https://docs.docker.com/engine/reference/commandline/stop/) will be used. +- `DOKKU_WAIT_TO_RETIRE`: (default: `60`) After a successful deploy, the grace period given to old containers before they are stopped/terminated. This is useful for ensuring completion of long-running http connections. + +The following settings may also be specified in the `CHECKS` file, though are available as environment variables in order to ease application reuse. + +- `DOKKU_CHECKS_WAIT`: (default: `5`) Wait this many seconds for the container to start before running checks. +- `DOKKU_CHECKS_TIMEOUT`: (default: `30`) Wait this many seconds for each response before marking it as a failure. +- `DOKKU_CHECKS_ATTEMPTS`: (default: `5`) Number of retries for to run for a specific check before marking it as a failure + +## Skipping and Disabling Checks + +> Note that `checks:disable` will now (as of 0.6.0) cause downtime for that process-type during deployments. Previously, it acted as `checks:skip` currently does. + +You can choose to skip checks completely on a per-application/per-process basis. Skipping checks will avoid the default 10 second waiting period entirely, as well as any other user-defined checks. ```shell +# process type specification is optional dokku checks:skip node-js-app worker,web ``` @@ -33,8 +47,7 @@ dokku checks:skip node-js-app worker,web DOKKU_CHECKS_SKIPPED: worker,web ``` -Additionally, any given process can only be configured to disable zero-downtime. example: - +Zero-downtime checks can also be disabled completely. This will stop old containers **before** new ones start, which may result in broken connections and downtime if your application fails to boot properly. ```shell dokku checks:disable node-js-app worker @@ -48,14 +61,67 @@ dokku checks:disable node-js-app worker DOKKU_CHECKS_SKIPPED: web ``` -Dokku will wait `60` seconds before stopping the old container so that existing connections are given a chance to complete. You can modify this value globally or on a per-application basis: +## Customizing Checks -```shell -dokku config:set --global DOKKU_WAIT_TO_RETIRE=120 -dokku config:set node-js-app DOKKU_WAIT_TO_RETIRE=120 +If your application needs a longer period to boot up - perhaps to load data into memory, or because of slow boot time - you may also use dokku's `checks` functionality to more precisely check whether an application can serve traffic or not. + +Checks are run against the detected `web` process from your application's `Procfile`. For non-web processes, Dokku will fallback to the aforementioned process uptime check. + +To specify checks, add a `CHECKS` file to the root of your project directory. The `CHECKS` file should be plain text and may contain: + +- Check instructions +- Settings (NAME=VALUE) +- Comments (lines starting with #) +- Empty lines + +> For dockerfile-based deploys, the file *must* be in `/app/CHECKS` within the container. `/app` is used by default as the root container directory for buildpack-based deploys. + +### Check Instructions + +The format of a check instruction is a path or relative URL, optionally followed by the expected content: + +``` +/about Our Amazing Team ``` -> Note that during this time, multiple containers may be running on your server, which can be an issue for memory-hungry applications on memory-constrained servers. +The `CHECKS` file can contain multiple checks: + +``` +/ My Amazing App +/stylesheets/index.css .body +/scripts/index.js $(function() +/images/logo.png +``` + +To check an application that supports multiple hostnames, use relative URLs that include the hostname: + +``` +//admin.example.com Admin Dashboard +//static.example.com/logo.png +``` + +You can also specify the protocol to explicitly check HTTPS requests: + +``` +https://admin.example.com Admin Dashboard +https://static.example.com/logo.png +``` + +While a full url may be used in order to invoke checks, if you are using relative urls, the port *must* be omitted. + +### Check Settings + +The default behavior is to wait for `5` seconds before running the checks, to timeout the checks after `30` seconds, and to attempt the checks `5` times. If the checks fail `5` times, the deployment is considered failed and the old container will continue serving traffic. + +You can change the default behavior by setting `WAIT`, `TIMEOUT`, and `ATTEMPTS` to different values in the `CHECKS` file: + +``` +WAIT=30 # Wait 1/2 minute +TIMEOUT=60 # Timeout after a minute +ATTEMPTS=10 # Attempt checks 10 times + +/ My Amazing App +``` ## Manually Invoking Checks @@ -143,90 +209,6 @@ dokku checks:run node-js-app web.3 Invalid container id specified (APP.web.3) ``` -## Customizing Checks - -If your application needs a longer period to boot up - perhaps to load data into memory, or because of slow boot time - you may also use dokku's `checks` functionality to more precisely check whether an application can serve traffic or not. - -Checks are run against the detected `web` process from your application's `Procfile`. For non-web processes, Dokku will fallback to the aforementioned process uptime check. - -To specify checks, add a `CHECKS` file to the root of your project directory. The `CHECKS` file should be plain text and may contain: - -* Check instructions -* Settings (NAME=VALUE) -* Comments (lines starting with #) -* Empty lines - -> For dockerfile-based deploys, the file *must* be in `/app/CHECKS` within the container. `/app` is used by default as the root container directory for buildpack-based deploys. - -### Check Instructions - -The format of a check instruction is a path or relative URL, optionally followed by the expected content: - -``` -/about Our Amazing Team -``` - -The `CHECKS` file can contain multiple checks: - -``` -/ My Amazing App -/stylesheets/index.css .body -/scripts/index.js $(function() -/images/logo.png -``` - -To check an application that supports multiple hostnames, use relative URLs that include the hostname: - -``` -//admin.example.com Admin Dashboard -//static.example.com/logo.png -``` - -You can also specify the protocol to explicitly check HTTPS requests: - -``` -https://admin.example.com Admin Dashboard -https://static.example.com/logo.png -``` - -While a full url may be used in order to invoke checks, if you are using relative urls, the port *must* be omitted. - -### Check Settings - -The default behavior is to wait for `5` seconds before running the checks, to timeout the checks after `30` seconds, and to attempt the checks `5` times. If the checks fail `5` times, the deployment is considered failed and the old container will continue serving traffic. - -You can change the default behavior by setting `WAIT`, `TIMEOUT`, and `ATTEMPTS` to different values in the `CHECKS` file: - -``` -WAIT=30 # Wait 1/2 minute -TIMEOUT=60 # Timeout after a minute -ATTEMPTS=10 # Attempt checks 10 times - -/ My Amazing App -``` - -You can also override the default `WAIT`, `TIMEOUT`, and `ATTEMPTS` variables for the global Dokku installation: - -```shell -dokku config:set --global DOKKU_CHECKS_WAIT=30 -dokku config:set --global DOKKU_CHECKS_TIMEOUT=60 -dokku config:set --global DOKKU_CHECKS_ATTEMPTS=10 -``` - -If your application runs multiple processes (a background worker configured in your `Procfile`, for example) and you have checks to ensure that your web application has booted up, you may want to disable the default check wait time for that application to avoid the `10` second wait per non-web process: - -```shell -dokku config:set node-js-app DOKKU_DEFAULT_CHECKS_WAIT=0 -``` - -### Configuring docker stop timeout - -[By default](https://docs.docker.com/engine/reference/commandline/stop/), docker will wait 10 seconds from the time the `stop` command is passed to a container before it attempts to kill said container. This timeout can be configured on a per-app basis in Dokku by setting the `DOKKU_DOCKER_STOP_TIMEOUT` configuration variable. This timeout applies to normal zero-downtime deployments as well as the `ps:stop` and `apps:destroy` commands. - -```shell -dokku config:set node-js-app DOKKU_DOCKER_STOP_TIMEOUT=20 -``` - ## Example: Successful Rails Deployment In this example, a Rails application is successfully deployed to dokku. The initial round of checks fails while the server is starting, but once it starts they succeed and the deployment is successful. `WAIT` is set to `10` because our application takes a while to boot up. `ATTEMPTS` is set to `6`, but the third attempt succeeds.