github/dokku
0
0
Fork 0
Code Issues Pull Requests Actions 1 Packages Projects Releases Wiki Activity

Merge pull request #1965 from trevorturk/checks-example-tweaks-2

Browse Source 
Checks example tweaks 2
This commit is contained in:
Jose Diaz-Gonzalez
2016-03-03 14:18:13 -05:00
parent 63fb33d03d bd5a7dea3a
commit 8a4926515b
1 changed files with 73 additions and 64 deletions
Download Patch File Download Diff File Expand all files Collapse all files

137
docs/checks-examples.md
View File

@@ -6,55 +6,48 @@ checks:disable <app>
checks:enable <app> Enable zero-downtime checks
```
Following a deploy, dokku will now wait `10` seconds before routing traffic to the new container. If the container is not running after this time, then the deploy is failed and your old container will continue serving traffic. You can modify this value using the following command:
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
```
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.
To specify checks, add a `CHECKS` file to the root of your project directory. This is a text file with one line per check. Empty lines and lines starting with `#` are ignored.
A check is a relative URL and may be followed by expected content from the page, for example:
```
/about Our Amazing Team
```
Dokku will wait `5` seconds before running the checks to give the server time to start. This value can be overridden on a per-app basis in the `CHECKS` file by setting `WAIT=nn`. You may also override this for the global dokku installation:
```shell
dokku config:set --global DOKKU_CHECKS_WAIT=15
```
Dokku will wait `60` seconds before stopping the old container so that existing connections are given a chance to complete. This value is also configurable globally:
```shell
dokku config:set --global 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.
Dokku will retry the checks `5` times until the checks are successful. If all 5 checks fail, the deployment is considered failed. This can be overridden in the `CHECKS` file by setting `ATTEMPTS=nn`. This number is also configurable globally:
```shell
dokku config:set --global DOKKU_CHECKS_ATTEMPTS=2
dokku config:set <app> DOKKU_DEFAULT_CHECKS_WAIT=30
```
You can also choose to skip checks completely on a per-application basis:
```shell
dokku checks:disable APP
dokku checks:disable <app>
```
## Checks Examples
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:
The CHECKS file may contain empty lines, comments (lines starting with #),
settings (NAME=VALUE) and check instructions.
```shell
dokku config:set --global DOKKU_WAIT_TO_RETIRE=120
dokku config:set <app> DOKKU_WAIT_TO_RETIRE=120
```
The format of a check instruction is a path, optionally followed by the
expected content. For example:
> 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.
## 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.
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
### 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
@@ -63,50 +56,65 @@ expected content. For example:
/images/logo.png
```
To check an application that supports multiple hostnames, use relative URLs
that include the hostname, for example:
To check an application that supports multiple hostnames, use relative URLs that include the hostname:
```
//admin.example.com Admin Dashboard
//admin.example.com Admin Dashboard
//static.example.com/logo.png
```
You can also specify the protocol to explicitly check HTTPS requests.
You can also specify the protocol to explicitly check HTTPS requests:
```
https://admin.example.com Admin Dashboard
https://admin.example.com Admin Dashboard
https://static.example.com/logo.png
```
The default behavior is to wait for 5 seconds before running the first check, and timeout each check to 30 seconds.
### Check Settings
By default, checks will be attempted 5 times. (Retried 4 times)
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 these by setting `WAIT`, `TIMEOUT` and `ATTEMPTS` to different values, for
example:
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
ATTEMPTS=10 # Attempt checks 10 times
/ My Amazing App
/ 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 <app> DOKKU_DEFAULT_CHECKS_WAIT=0
```
## 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. `ATTEMPTS` is set to 6, but the third attempt succeeds.
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.
### CHECKS file
````
WAIT=5
WAIT=10
ATTEMPTS=6
/check.txt simple_check
/check.txt simple_check
````
> check.txt is a text file returning the string 'simple_check'
For this check to work, we've added a line to `config/routes.rb` that simply returns a string:
````
get '/check.txt', to: proc {[200, {}, ['simple_check']]}
````
### Deploy Output
@@ -129,19 +137,19 @@ git push dokku master
-----> Releasing myapp...
-----> Deploying myapp...
-----> Running pre-flight checks
-----> Attempt 1/6 Waiting for 5 seconds ...
-----> Attempt 1/6 Waiting for 10 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.
-----> Attempt 2/6 Waiting for 5 seconds ...
-----> Attempt 2/6 Waiting for 10 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.
-----> Attempt 3/6 Waiting for 5 seconds ...
-----> Attempt 3/6 Waiting for 10 seconds ...
CHECKS expected result:
http://localhost/check.txt => "simple_check"
-----> All checks successful!
@@ -165,14 +173,15 @@ curl: (7) Failed to connect to 172.17.0.155 port 5000: Connection refused
````
## 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.
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 attempts have been exceeded, the deployment fails and we see the container output, which shows the Postgres connection errors.
### CHECKS file
````
WAIT=5
WAIT=10
ATTEMPTS=6
/
````
@@ -200,37 +209,37 @@ Procfile declares types -> web
Releasing myapp...
Deploying myapp...
Running pre-flight checks
-----> Attempt 1/6 Waiting for 5 seconds ...
-----> Attempt 1/6 Waiting for 10 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.
-----> Attempt 2/6 Waiting for 5 seconds ...
-----> Attempt 2/6 Waiting for 10 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.
-----> Attempt 3/6 Waiting for 5 seconds ...
-----> Attempt 3/6 Waiting for 10 seconds ...
CHECKS expected result:
http://localhost/ => ""
!
curl: (22) The requested URL returned error: 500 Internal Server Error
! Check attempt 3/6 failed.
-----> Attempt 4/6 Waiting for 5 seconds ...
-----> Attempt 4/6 Waiting for 10 seconds ...
CHECKS expected result:
http://localhost/ => ""
!
curl: (22) The requested URL returned error: 500 Internal Server Error
! Check attempt 4/6 failed.
-----> Attempt 5/6 Waiting for 5 seconds ...
-----> Attempt 5/6 Waiting for 10 seconds ...
CHECKS expected result:
http://localhost/ => ""
!
curl: (22) The requested URL returned error: 500 Internal Server Error
! Check attempt 5/6 failed.
-----> Attempt 6/6 Waiting for 5 seconds ...
-----> Attempt 6/6 Waiting for 10 seconds ...
CHECKS expected result:
http://localhost/ => ""
!