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

Merge pull request #2336 from dokku/clarify-documentation

Browse Source 
Clarify documentation
This commit is contained in:
Jose Diaz-Gonzalez
2016-07-30 17:12:55 -04:00
committed by GitHub
parent 12360639bb 60a44c88af
commit 4f17e0fa04
9 changed files with 262 additions and 72 deletions
Download Patch File Download Diff File Expand all files Collapse all files

2
docs/advanced-usage/repository-management.md
View File

@@ -9,7 +9,7 @@ repo:purge-cache <app> # Deletes the contents of the build cac
The repository plugin is meant to allow users to perform management commands against a repository.
# Git Garbage Collection
## 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.

55
docs/assets/style.css
View File

@@ -381,6 +381,61 @@ blockquote {
.clearfix:after {
clear: both
}
.improve-slideout {
position: fixed;
bottom: 66%;
right: 0;
-webkit-transition-duration: 0.3s;
-moz-transition-duration: 0.3s;
-o-transition-duration: 0.3s;
transition-duration: 0.3s;
background: #363637;
padding: 5px 0 4px;
z-index: 90;
}
.improve-slideout:hover {
right: 205px;
}
.improve-slideout:hover .improve-slideout-inner {
right: 0;
}
.improve-slideout-inner {
position: fixed;
bottom: 66%;
right: -205px;
-webkit-transition-duration: 0.3s;
-moz-transition-duration: 0.3s;
-o-transition-duration: 0.3s;
transition-duration: 0.3s;
background: #e0e0d9;
padding: 4px 12px;
width: 205px;
}
.improve-slideout-inner h6 {
color: #363637;
font-weight: 700;
text-transform: uppercase;
margin: 0;
font-size: 14px;
}
.git-improve {
font-size: 20px;
vertical-align: -2px;
padding-left: 8px;
}
.back-to-contents {
position: fixed;
bottom: calc(66% - 34px);
right: 0;
background: #363637;
padding: 5px 0 4px;
z-index: 90;
}
.icon-improve {
color: #bdbdb5;
padding: 2px 9px 0 10px;
font-size: 14px;
}
a .fa {
display: inline-block;
text-decoration: inherit

2
docs/configuration/nginx.md
View File

@@ -12,7 +12,7 @@ nginx:error-logs <app> [-t] # Show the nginx error logs for an appl
> New as of 0.5.0
Dokku uses a templating library by the name of [sigil](https://github.com/gliderlabs/sigil) to generate nginx configuration for each app. If you'd like to provide a custom template for your application, there are a couple options:
Dokku uses a templating library by the name of [sigil](https://github.com/gliderlabs/sigil) to generate nginx configuration for each app. You may also provide a custom template for your application as follows:
- Copy the following example template to a file named `nginx.conf.sigil` and either:
- check it into the root of your app repo for buildpack applications

2
docs/deployment/methods/dockerfiles.md
View File

@@ -21,7 +21,7 @@ Dokku will extract all tcp ports exposed using the `EXPOSE` directive (one port
If you do not explicitly `EXPOSE` a port in your `Dockerfile`, dokku will configure the nginx proxy to listen on port 80 (and 443 for TLS) and forward traffic to your app listening on port 5000 inside the container. Just like buildpack apps, you can also use the `$PORT` environment variable in your app to maintain portability.
When ports are exposed through the default nginx proxy, they are proxied externally as HTTP ports. At this time, in no case do we proxy plain TCP or UDP ports. If you'd like to investigate alternative proxy methods, please refer to our [proxy management documentation](/dokku/advanced-usage/proxy-management/).
When ports are exposed through the default nginx proxy, they are proxied externally as HTTP ports. At this time, in no case do we proxy plain TCP or UDP ports. If you would like to investigate alternative proxy methods, please refer to our [proxy management documentation](/dokku/advanced-usage/proxy-management/).
## Customizing the run command

50
docs/deployment/process-management.md
View File

@@ -1,8 +1,6 @@
# Process/Container management
# Process and Container Management
> New as of 0.3.14
Dokku supports rudimentary process (really container) management via the `ps` plugin.
> New as of 0.3.14, Enhanced in 0.7.0
```
ps <app> # List processes running in app container(s)
@@ -13,11 +11,21 @@ ps:restart <app> # Restart app container(s)
ps:scale <app> <proc>=<count> [<proc>=<count>] # Set how many processes of a given process to run
ps:start <app> # Start app container(s)
ps:stop <app> # Stop app container(s)
ps:restart-policy <app> # Shows the restart-policy for an app
ps:set-restart-policy <app> <policy> # Sets app restart-policy
```
## Scaling
By default, Dokku will only start a single `web` process - if defined - though process scaling can be managed by the `ps` plugin or via a custom `DOKKU_SCALE` file.
Dokku allows you to run multiple process types at different container counts. For example, if you had an app that contained 1 web app listener and 1 background job processor, dokku can, spin up 1 container for each process type defined in the Procfile. *By default, dokku will only start a single web process (if defined.)* However, if you wanted, for example, 2 job processors running simultaneously, you can modify this behavior in one of the following ways.
> The `web` proctype is the only proctype that will invoke custom checks as defined by a CHECKS file. It is also the only process type that will be launched in a container that is either proxied via nginx or bound to an external port.
### `ps:scale` command
Dokku can also manage scaling itself via the `ps:scale` command. This command can be used to scale multiple process types at the same time.
```shell
dokku ps:scale APP web=1 worker=2
```
### DOKKU_SCALE file
@@ -30,17 +38,29 @@ web=1
worker=2
```
### `ps:scale` command
> *NOTE*: Dokku will always use the DOKKU_SCALE file that ships with the repo to override any local settings.
Dokku can also manage scaling itself via the `ps:scale` command. This command can be used to scale multiple process types at the same time.
## Restart Policies
> New as of 0.7.0
By default, Dokku will automatically restart containers that exit with a non-zero status up to 10 times via the [on-failure Docker restart policy](https://docs.docker.com/engine/reference/run/#restart-policies-restart). You can configure this via the relevant `ps` commands:
```shell
dokku ps:scale app_name web=1 worker=2
# always restart an exited container
dokku ps:set-restart-policy node-js-app always
# never restart an exited container
dokku ps:set-restart-policy node-js-app no
# only restart it on Docker restart if it was not manually stopped
dokku ps:set-restart-policy node-js-app unless-stopped
# restart only on non-zero exit status
dokku ps:set-restart-policy node-js-app on-failure
# restart only on non-zero exit status up to 20 times
dokku ps:set-restart-policy node-js-app on-failure:20
```
*NOTE*: Dokku will always use the DOKKU_SCALE file that ships with the repo to override any local settings.
## The web proctype
Like Heroku, we handle the `web` proctype differently from others. The `web` proctype is the only proctype that will invoke custom checks as defined by a CHECKS file. It is also the only proctype that will be launched in a container that is either proxied via nginx or bound to an external port.
Restart policies have no bearing on server reboot, and Dokku will always attempt to restart your applications at that point unless they were manually stopped.

55
docs/deployment/user-management.md
View File

@@ -1,44 +1,47 @@
# User Management
> New as of 0.7.0
```
ssh-keys:add <name> [/path/to/key] # Add a new public key by pipe or path
ssh-keys:list # List of all authorized Dokku public ssh keys
ssh-keys # Manage public ssh keys that are allowed to connect to Dokku
ssh-keys:remove <name> # Remove SSH public key by name
```
When pushing to Dokku, ssh key based authorization is the preferred authentication method, for ease of use and increased security.
Users in Dokku are managed via the `~/dokku/.ssh/authorized_keys` file. It is **highly** recommended that you follow the steps below to manage users on a Dokku server.
## Dokku ssh-keys command
The `dokku ssh-keys` command(s) allow you to manage ssh keys used to push to the Dokku server. The following is the usage output for `dokku ssh-keys`:
```
$ dokku ssh-keys:help
Usage: dokku ssh-keys[:COMMAND]
Manage public ssh keys that are allowed to connect to Dokku
Additional commands:
ssh-keys:add <name> [/path/to/key] Add a new public key by pipe or path
ssh-keys:list List of all authorized Dokku public ssh keys
ssh-keys Manage public ssh keys that are allowed to connect to Dokku
ssh-keys:remove <name> Remove SSH public key by name
```
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. In Dokku's case, the unique _name_ is just for ease of identifying the keys, the ssh (git) user is *always* `dokku`, as this is the system user that the `dokku` binary uses to perform all it's actions.
> Users of older versions of Dokku should use the `sshcommand` binary to manage keys. Please refer to the Dokku documentation for your version for more details.
## Adding deploy users
You can add your public key to Dokku with the following command:
`NAME` is the username prefer to use to refer to this particular key. Including the word `admin` in the name will grant the user privileges to add additional keys remotely.
```shell
$ dokku ssh-keys:add <NAME> <PATH/TO/KEY>
dokku ssh-keys:add KEY_NAME path/to/id_rsa.pub
```
Admin users and root can also add keys remotely:
```shell
cat <PATH/TO/KEY> | ssh dokku@dokku.me ssh-keys:add <NAME>
`KEY_NAME` is the username prefer to use to refer to this particular key. Including the word `admin` in the name will grant the user privileges to add additional keys remotely.
Key names are unique, and attempting to re-use a name will result in an error.
> The unique `KEY_NAME` is for ease of identifying the keys. The ssh (git) user is *always* `dokku`, as this is the system user that the `dokku` binary uses to perform all it's actions.
As key names are unique, they can be used to remove a public ssh key:
```SHELL
dokku ssh-keys:remove KEY_NAME
```
If you are using the vagrant installation, you can also use the `make vagrant-acl-add` target to add your public key to dokku (it will use your host username as the `USER`):
Admin users and root can also add keys remotely:
```shell
cat ~/.ssh/id_rsa.pub | ssh dokku@dokku.me ssh-keys:add KEY_NAME
```
Finally, if you are using the vagrant installation, you can also use the `make vagrant-acl-add` target to add your public key to Dokku (it will use your host username as the `USER`):
```shell
cat ~/.ssh/id_rsa.pub | make vagrant-acl-add
@@ -46,4 +49,4 @@ cat ~/.ssh/id_rsa.pub | make vagrant-acl-add
## Scoping commands to specific users
See the [user auth plugin trigger documentation](/dokku/development/plugin-triggers/#user-auth).
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. Please see the documentation on that trigger for more information.

52
docs/deployment/zero-downtime-deploys.md
View File

@@ -57,11 +57,17 @@ dokku config:set <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.
## Manually Invoking Checks
Checks can also be manually invoked via the `checks:run` command. This can be used to check the status of an application via cron to provide integration with external healthchecking software.
Checks are run against a specific application:
```shell
dokku checks:run APP
```
```
# checks are run against a specific application
$ dokku checks:run APP
-----> Running pre-flight checks
-----> Running checks for app (APP.web.1)
For more efficient zero downtime deployments, create a file CHECKS.
@@ -81,9 +87,15 @@ $ dokku checks:run APP
CHECKS file not found in container: Running simple container check...
-----> Waiting for 10 seconds ...
-----> Default container check successful!
```
# checks can be scoped to a particular process type
$ dokku checks:run APP worker
Checks can be scoped to a particular process type:
```shell
dokku checks:run APP worker
```
```
-----> Running pre-flight checks
-----> Running checks for app (APP.worker.1)
For more efficient zero downtime deployments, create a file CHECKS.
@@ -91,9 +103,15 @@ $ dokku checks:run APP worker
CHECKS file not found in container: Running simple container check...
-----> Waiting for 10 seconds ...
-----> Default container check successful!
```
# a container id may also be specified
$ dokku checks:run APP web.2
An app process id may also be specified:
```shell
dokku checks:run APP web.2
```
```
-----> Running pre-flight checks
-----> Running checks for app (APP.web.2)
For more efficient zero downtime deployments, create a file CHECKS.
@@ -101,19 +119,31 @@ $ dokku checks:run APP web.2
CHECKS file not found in container: Running simple container check...
-----> Waiting for 10 seconds ...
-----> Default container check successful!
```
# non-existent process types will result in an error
$ dokku checks:run APP non-existent
Non-existent process types will result in an error:
```shell
dokku checks:run APP non-existent
```
```
-----> Running pre-flight checks
Invalid process type specified (APP.non-existent)
```
# non-existent container ids will *also* result in an error
$ dokku checks:run APP web.3
Non-existent process ids will *also* result in an error
```shell
dokku checks:run APP web.3
```
```
-----> Running pre-flight checks
Invalid container id specified (APP.web.3)
```
## Checks
## 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.

37
docs/development/testing.md
View File

@@ -1,21 +1,24 @@
# Dokku test suite
Dokku now has a full test suite to assist in quick iterating development. These tests include a linter using [shellcheck](https://github.com/koalaman/shellcheck), functional unit tests using the [bats testing framework](https://github.com/sstephenson/bats), and a deployment suite of example apps that use the most popular languages and frameworks.
Dokku has a full test suite to assist in quick iterating development. These tests include a linter using [shellcheck](https://github.com/koalaman/shellcheck), functional unit tests using the [bats testing framework](https://github.com/sstephenson/bats), and a deployment suite of example apps that use the most popular languages and frameworks.
Bats tests can be found here:
```
tests/unit/*.bats
```
We maintain the Dokku test harness within the `tests` directory:
Example apps can be found here:
```
tests/apps/
```
- `tests/unit/*.bats`: Bats tests
- `tests/apps/`: Example applications that can be used for tests
### Executing tests locally
## Continuous Integration
All pull requests have tests run against them on [CircleCI](https://circleci.com/), a continuous integration platform that provides Docker support for Ubuntu Trusty 14.04.
If you wish to skip tests for a particular commit - e.g. Documentation changes - you may add the `[ci skip]` designator to your commit message. Commits that *should* be tested but have the above designator will not be merged.
While we do provide official packages for a variety of platforms, as our test suite currently runs on Ubuntu Trusty 14.04, we only provide official installation support for that platform.
## Local Test Execution
- Setup dokku in a [vagrant vm](/dokku/getting-started/install/vagrant)
- Test setup and execution
- Run the following to setup tests and execute them:
```shell
vagrant ssh
@@ -35,9 +38,11 @@ Example apps can be found here:
# execute all app deployment tests
make deploy-tests
```
- Additionally you may run a specific app deployment tests with a target similar to:
```shell
$ make deploy-test-nodejs-express
```
- For a full list of test make targets check out `tests.mk` in the root of the dokku repository.
Additionally you may run a specific app deployment tests with a target similar to:
```shell
make deploy-test-nodejs-express
```
For a full list of test make targets check out `tests.mk` in the root of the dokku repository.

79
docs/template.html
View File

@@ -80,6 +80,61 @@
background-color: #000;
padding: 10px;
}
.improve-slideout {
position: fixed;
bottom: 66%;
right: 0;
-webkit-transition-duration: 0.3s;
-moz-transition-duration: 0.3s;
-o-transition-duration: 0.3s;
transition-duration: 0.3s;
background: #363637;
padding: 5px 0px 4px;
z-index: 90;
}
.improve-slideout:hover {
right: 205px;
}
.improve-slideout:hover .improve-slideout-inner {
right: 0;
}
.improve-slideout-inner {
position: fixed;
bottom: 66%;
right: -205px;
-webkit-transition-duration: 0.3s;
-moz-transition-duration: 0.3s;
-o-transition-duration: 0.3s;
transition-duration: 0.3s;
background: #e0e0d9;
padding: 4px 12px;
width: 205px;
}
.improve-slideout-inner h6 {
color: #363637;
font-weight: 700;
text-transform: uppercase;
margin: 0;
font-size: 14px;
}
.git-improve {
font-size: 20px;
vertical-align: -2px;
padding-left: 8px;
}
.back-to-contents {
position: fixed;
bottom: calc(66% - 34px);
right: 0;
background: #363637;
padding: 5px 0px 4px;
z-index: 90;
}
.icon-improve {
color: #bdbdb5;
padding: 2px 9px 0 10px;
font-size: 14px;
}
</style>
</head>
<body>
@@ -116,6 +171,14 @@
</div>
<div class="container-fluid">
<div class="improve-slideout">
<i class="fa fa-pencil icon-improve"></i>
<a href="https://github.com/{{USER}}/{{NAME}}/edit/master/docs/{{DOC}}" target="_blank">
<div class="improve-slideout-inner"><h6>Improve This Doc <i class="fa fa-github git-improve"></i></h6></div>
</a>
</div>
<a class="back-to-contents" href="#page-contents"><i class="fa fa-arrow-circle-up icon-improve" title="Back to Contents"></i></a>
<div class="row">
<div class="col-xs-8 col-md-6 col-md-push-4 markdown-body" style="padding-top:16px">
{{CONTENT}}
@@ -134,7 +197,7 @@
<a href="/{{NAME}}/deployment/application-management/" class="list-group-item">Application Management</a>
<a href="/{{NAME}}/deployment/remote-commands/" class="list-group-item">Remote Commands</a>
<a href="/{{NAME}}/deployment/one-off-processes/" class="list-group-item">One Off Processes/Cron</a>
<a href="/{{NAME}}/deployment/process-management/" class="list-group-item">Scaling Apps</a>
<a href="/{{NAME}}/deployment/process-management/" class="list-group-item">Process Scaling</a>
<a href="/{{NAME}}/deployment/user-management/" class="list-group-item">User Management</a>
<a href="/{{NAME}}/deployment/zero-downtime-deploys/" class="list-group-item">Zero Downtime Deploy Checks</a>
@@ -253,6 +316,7 @@
var tables = document.querySelectorAll('table'),
blockquotes = document.querySelectorAll('blockquote'),
versionList = document.querySelectorAll('.rst-other-versions dl')[0],
backToContentsEl = document.querySelectorAll('.back-to-contents')[0]
currentVersionEl = document.querySelectorAll('.rst-current-version')[0],
currentVersion = currentVersionEl.getAttribute('data-ref'),
versionContainer = document.querySelectorAll('.rst-versions.rst-badge')[0],
@@ -312,6 +376,19 @@
return language;
};
addListener(backToContentsEl, 'click', function(e) {
e.preventDefault();
var scrollToTop = window.setInterval(function() {
var pos = window.pageYOffset;
if ( pos > 0 ) {
window.scrollTo( 0, pos - 20 );
} else {
window.clearInterval( scrollToTop );
}
}, 1);
return false;
});
var ls2 = {
save : function (key, jsonData, expirationMS) {
if (typeof (Storage) === 'undefined') { return false; }