From 4a0c0eab25a01b6296b0bd590a92b13d025af41f Mon Sep 17 00:00:00 2001 From: Josh Cohen Date: Thu, 26 Mar 2015 18:29:39 -0400 Subject: [PATCH 1/3] add documentation --- docs/application-deployment.md | 6 +- docs/checks-examples.md | 201 +++++++++++++++++++++++++++++++++ 2 files changed, 206 insertions(+), 1 deletion(-) create mode 100644 docs/checks-examples.md diff --git a/docs/application-deployment.md b/docs/application-deployment.md index 9327ca13e..ab8274028 100644 --- a/docs/application-deployment.md +++ b/docs/application-deployment.md @@ -107,10 +107,14 @@ A check is a relative URL and may be followed by expected content from the page, /about Our Amazing Team ``` -Dokku will wait `DOKKU_CHECKS_WAIT` seconds (default: `5`) before running the checks to give server time to start. For shorter/longer wait, change the `DOKKU_CHECKS_WAIT` environment variable. +Dokku will wait `DOKKU_CHECKS_WAIT` seconds (default: `5`) before running the checks to give server time to start. For shorter/longer wait, change the `DOKKU_CHECKS_WAIT` environment variable. This can be overridden in the CHECKS file by setting WAIT=nn. Dokku will wait `DOKKU_WAIT_TO_RETIRE` seconds (default: `60`) before stopping the old container such that no existing connections to it are dropped. +Dokku will retry the checks DOKKU_CHECKS_RETRIES times until the checks are successful or DOKKU_CHECKS_RETRIES is exceeded. In the latter case, the deployment is considered failed. This can be overridden in the CHECKS file by setting RETRIES=nn. + +See [checks-examples.md](checks-examples.md) for examples and output. + # Removing a deployed app SSH onto the server, then execute: diff --git a/docs/checks-examples.md b/docs/checks-examples.md new file mode 100644 index 000000000..e03fb5227 --- /dev/null +++ b/docs/checks-examples.md @@ -0,0 +1,201 @@ +# Checks Examples + +The CHECKS file may contain empty lines, comments (lines starting with #), +settings (NAME=VALUE) and check instructions. + +The format of a check instruction is a path, optionally followed by the +expected content. For example: + + / 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, for example: + + //admin.example.com Admin Dashboard + //static.example.com/logo.png + +You can also specify the protocol to explicitly check HTTPS requests. + +The default behavior is to wait for 5 seconds before running the first check, +and timeout each check to 30 minutes. + +By default, checks will be retried 5 times. + +You can change these by setting WAIT, TIMEOUT and RETRIES to different values, for +example: + + WAIT=30 # Wait 1/2 minute + TIMEOUT=60 # Timeout after a minute + RETRIES=10 # retry checks 10 times + +# Example: Successful Rails Deployment +In this example, a rails applicaiton 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. +RETRIES is set to 6, but the third attempt succeeds. + +## CHECKS file + +```` +WAIT=5 +RETRIES=6 +/check.txt simple_check +```` + +> check.txt is a text file returning the string 'simple_check' + +## Deploy Output + +```` +git push dokku master + +-----> Cleaning up... +-----> Building tcfpledge2 from buildstep... +-----> Adding BUILD_ENV to build environment... +-----> Ruby app detected +-----> Compiling Ruby/Rails +-----> Using Ruby version: ruby-2.0.0 + +..... + +-----> Discovering process types + Procfile declares types -> web +-----> Releasing myapp... +-----> Deploying myapp... +-----> Running pre-flight checks +-----> Attempt 1/6 Waiting for 5 seconds ... + CHECKS expected result: + http://localhost/check.txt => "simple_check" + ! +curl: (7) Failed to connect to 172.17.0.155 port 5000: Connection refused + ! Check attempt 1/6 failed. Retrying... +-----> Attempt 2/6 Waiting for 5 seconds ... + CHECKS expected result: + http://localhost/check.txt => "simple_check" + ! +curl: (7) Failed to connect to 172.17.0.155 port 5000: Connection refused + ! Check attempt 2/6 failed. Retrying... +-----> Attempt 3/6 Waiting for 5 seconds ... + CHECKS expected result: + http://localhost/check.txt => "simple_check" +-----> All checks successful! +=====> myapp container output: + => Booting Thin + => Rails 4.2.0 application starting in production on http://0.0.0.0:5000 + => Run `rails server -h` for more startup options + => Ctrl-C to shutdown server + Thin web server (v1.6.3 codename Protein Powder) + Maximum connections set to 1024 + Listening on 0.0.0.0:5000, CTRL+C to stop +=====> end myapp container output +-----> Running post-deploy +-----> Configuring myapp.dokku.example.com... +-----> Creating http nginx.conf +-----> Running nginx-pre-reload + Reloading nginx +-----> Shutting down old container in 60 seconds +=====> Application deployed: + http://myapp.dokku.example.com +```` + +# Example: Failing Rails Deployment +In this example, a Rails application fails to deploy. The reason for the failure is that the postgres database connection fails. The initial checks will fail while we wait for the server to start up, just like in the above example. However, once the server does start accepting connections, we will see an error 500 due to the postgres database connection failure. + +Once the retries have been exceeded, the deployment fails and we see the container output, which shows the Postgres connection errors. + +## CHECKS file + +```` +WAIT=5 +RETRIES=6 +/ +```` + +> The check to the root url '/' would normally access the database. + +## Deploy Output + +> Note: The output has been trimmed for brevity + +```` +git push dokku master + +-----> Cleaning up... +-----> Building tcfpledge2 from buildstep... +-----> Adding BUILD_ENV to build environment... +-----> Ruby app detected +-----> Compiling Ruby/Rails +-----> Using Ruby version: ruby-2.0.0 + +..... + +Discovering process types +Procfile declares types -> web +Releasing myapp... +Deploying myapp... +Running pre-flight checks +-----> Attempt 1/6 Waiting for 5 seconds ... + CHECKS expected result: + http://localhost/ => "" + ! +curl: (7) Failed to connect to 172.17.0.188 port 5000: Connection refused + ! Check attempt 1/6 failed. Retrying... +-----> Attempt 2/6 Waiting for 5 seconds ... + CHECKS expected result: + http://localhost/ => "" + ! +curl: (7) Failed to connect to 172.17.0.188 port 5000: Connection refused + ! Check attempt 2/6 failed. Retrying... +-----> Attempt 3/6 Waiting for 5 seconds ... + CHECKS expected result: + http://localhost/ => "" + ! +curl: (22) The requested URL returned error: 500 Internal Server Error + ! Check attempt 3/6 failed. Retrying... +-----> Attempt 4/6 Waiting for 5 seconds ... + CHECKS expected result: + http://localhost/ => "" + ! +curl: (22) The requested URL returned error: 500 Internal Server Error + ! Check attempt 4/6 failed. Retrying... +-----> Attempt 5/6 Waiting for 5 seconds ... + CHECKS expected result: + http://localhost/ => "" + ! +curl: (22) The requested URL returned error: 500 Internal Server Error + ! Check attempt 5/6 failed. Retrying... +-----> Attempt 6/6 Waiting for 5 seconds ... + CHECKS expected result: + http://localhost/ => "" + ! +curl: (22) The requested URL returned error: 500 Internal Server Error +Could not start due to 1 failed checks. + ! Check attempt 6/6 failed. Retrying... +=====> myapp container output: + => Booting Thin + => Rails 4.2.0 application starting in production on http://0.0.0.0:5000 + => Run `rails server -h` for more startup options + => Ctrl-C to shutdown server + Thin web server (v1.6.3 codename Protein Powder) + Maximum connections set to 1024 + Listening on 0.0.0.0:5000, CTRL+C to stop + Started GET "/" for 172.17.42.1 at 2015-03-26 21:36:47 +0000 + Is the server running on host "172.17.42.1" and accepting + TCP/IP connections on port 5431? + PG::ConnectionBad (could not connect to server: Connection refused + Is the server running on host "172.17.42.1" and accepting + TCP/IP connections on port 5431? + ): + vendor/bundle/ruby/2.0.0/gems/activerecord-4.2.0/lib/active_record/connection_adapters/postgresql_adapter.rb:651:in `initialize' + vendor/bundle/ruby/2.0.0/gems/activerecord-4.2.0/lib/active_record/connection_adapters/postgresql_adapter.rb:651:in `new' + vendor/bundle/ruby/2.0.0/gems/activerecord-4.2.0/lib/active_record/connection_adapters/postgresql_adapter.rb:651:in `connect' + vendor/bundle/ruby/2.0.0/gems/activerecord-4.2.0/lib/active_record/connection_adapters/postgresql_adapter.rb:242:in `initialize' + vendor/bundle/ruby/2.0.0/gems/activerecord-4.2.0/lib/active_record/connection_adapters/postgresql_adapter.rb:44:in `new' + vendor/bundle/ruby/2.0.0/gems/activerecord-4.2.0/lib/active_record/connection_adapters/postgresql_adapter.rb:44:in `postgresql_connection +=====> end myapp container output +/usr/local/bin/dokku: line 49: 23409 Killed dokku deploy "$APP" +To dokku@dokku.example.com:myapp + ! [remote rejected] dokku -> master (pre-receive hook declined) +error: failed to push some refs to 'dokku@dokku.example.com:myapp' +```` \ No newline at end of file From f90c7b95249eff7fc00d4c9730423d013f8dbd1a Mon Sep 17 00:00:00 2001 From: Josh Cohen Date: Thu, 26 Mar 2015 18:32:50 -0400 Subject: [PATCH 2/3] docs tweak --- docs/checks-examples.md | 2 ++ 1 file changed, 2 insertions(+) diff --git a/docs/checks-examples.md b/docs/checks-examples.md index e03fb5227..9e371f96b 100644 --- a/docs/checks-examples.md +++ b/docs/checks-examples.md @@ -47,6 +47,8 @@ RETRIES=6 ## Deploy Output +> Note: The output has been trimmed for brevity + ```` git push dokku master From b33aebcae28a5b8cb108d9c714c4a24de20caa9d Mon Sep 17 00:00:00 2001 From: Josh Date: Thu, 26 Mar 2015 19:13:45 -0400 Subject: [PATCH 3/3] sanitize example app name --- docs/checks-examples.md | 6 +++--- 1 file changed, 3 insertions(+), 3 deletions(-) diff --git a/docs/checks-examples.md b/docs/checks-examples.md index 9e371f96b..6881fa644 100644 --- a/docs/checks-examples.md +++ b/docs/checks-examples.md @@ -53,7 +53,7 @@ RETRIES=6 git push dokku master -----> Cleaning up... ------> Building tcfpledge2 from buildstep... +-----> Building myapp from buildstep... -----> Adding BUILD_ENV to build environment... -----> Ruby app detected -----> Compiling Ruby/Rails @@ -124,7 +124,7 @@ RETRIES=6 git push dokku master -----> Cleaning up... ------> Building tcfpledge2 from buildstep... +-----> Building myapp from buildstep... -----> Adding BUILD_ENV to build environment... -----> Ruby app detected -----> Compiling Ruby/Rails @@ -200,4 +200,4 @@ Could not start due to 1 failed checks. To dokku@dokku.example.com:myapp ! [remote rejected] dokku -> master (pre-receive hook declined) error: failed to push some refs to 'dokku@dokku.example.com:myapp' -```` \ No newline at end of file +````