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

Merge pull request #3453 from jayjun/deployment

Browse Source 
Fix Deployment guides style
This commit is contained in:
Jose Diaz-Gonzalez
2019-02-19 10:41:42 -05:00
committed by GitHub
parent 42b6876f2c e839c29916
commit e3f0e09a4a
14 changed files with 142 additions and 143 deletions
Download Patch File Download Diff File Expand all files Collapse all files

24
docs/deployment/application-deployment.md
View File

@@ -1,6 +1,6 @@
# Deploying to Dokku
> Note: This document uses the hostname `dokku.me` in commands. For your server please
> Note: This document uses the hostname `dokku.me` in commands. For your server, please
> substitute your server's hostname instead.
## Deploy tutorial
@@ -15,7 +15,7 @@ git clone git@github.com:heroku/ruby-rails-sample.git
### Create the app
Create the application on the Dokku host. You will need to ssh onto the host to run this command.
Create the application on the Dokku host. You will need to SSH onto the host to run this command.
```shell
# on the Dokku host
@@ -52,7 +52,7 @@ dokku postgres:link rails-database ruby-rails-sample
### Deploy the app
> Warning: Your application _should_ respect the `PORT` environment variable or it may not respond to web requests.
> Warning: Your application *should* respect the `PORT` environment variable or it may not respond to web requests.
> Please see the [port management documentation](/docs/networking/port-management.md) for details.
Now you can deploy the `ruby-rails-sample` app to your Dokku server. All you have to do is add a remote to name the app. Applications are created on-the-fly on the Dokku server.
@@ -100,7 +100,7 @@ Total 231 (delta 93), reused 147 (delta 53)
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/).
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/).
### Skipping deployment
@@ -112,9 +112,9 @@ If you only want to rebuild and tag a container, you can skip the deployment pha
dokku config:set ruby-rails-sample DOKKU_SKIP_DEPLOY=true
```
### Re-Deploying / restarting
### Redeploying or restarting
If you need to re-deploy (or restart) your app:
If you need to redeploy (or restart) your app:
```shell
# on the Dokku host
@@ -125,7 +125,7 @@ See the [process scaling documentation](/docs/deployment/process-management.md)
### Deploying with private git submodules
Dokku uses git locally (i.e. not a docker image) to build its own copy of your app repo, including submodules. This is done as the `dokku` user. Therefore, in order to deploy private git submodules, you'll need to drop your deploy key in `/home/dokku/.ssh/` and potentially add github.com (or your VCS host key) into `/home/dokku/.ssh/known_hosts`. The following test should help confirm you've done it correctly.
Dokku uses Git locally (i.e. not a Docker image) to build its own copy of your app repo, including submodules. This is done as the `dokku` user. Therefore, in order to deploy private Git submodules, you'll need to drop your deploy key in `/home/dokku/.ssh/` and potentially add `github.com` (or your VCS host key) into `/home/dokku/.ssh/known_hosts`. The following test should help confirm you've done it correctly.
```shell
# on the Dokku host
@@ -134,7 +134,7 @@ ssh-keyscan -t rsa github.com >> ~/.ssh/known_hosts
ssh -T git@github.com
```
Note that if the buildpack or dockerfile build process require ssh key access for other reasons, the above may not always apply.
Note that if the buildpack or Dockerfile build process require SSH key access for other reasons, the above may not always apply.
## Deploying to subdomains
@@ -180,9 +180,9 @@ git push dokku master
remote: -----> Application deployed:
remote: http://dokku.me
## Dokku/Docker Container Management Compatibility
## Dokku/Docker container management compatibility
Dokku is, at its core, a docker container manager. Thus, it does not necessarily play well with other out-of-band processes interacting with the docker daemon. One thing to note as in [issue #1220](https://github.com/dokku/dokku/issues/1220), dokku executes a cleanup function prior to every deployment.
Dokku is, at its core, a Docker container manager. Thus, it does not necessarily play well with other out-of-band processes interacting with the Docker daemon. One thing to note as in [issue #1220](https://github.com/dokku/dokku/issues/1220), Dokku executes a cleanup function prior to every deployment.
As of 0.5.x, this function removes all containers with the label `dokku` where the status is either `dead` or `exited`, as well as all `dangling` images. Previous versions would remove `dead` or `exited` containers, regardless of their label.
@@ -196,11 +196,11 @@ See the [nginx documentation](/docs/configuration/nginx.md#default-site).
## Deploying non-master branch
See the [git documentation](/docs/deployment/methods/git.md#changing-the-deploy-branch).
See the [Git documentation](/docs/deployment/methods/git.md#changing-the-deploy-branch).
## Dockerfile deployment
See the [dockerfile documentation](/docs/deployment/methods/dockerfiles.md).
See the [Dockerfile documentation](/docs/deployment/methods/dockerfiles.md).
## Image tagging

17
docs/deployment/application-management.md
View File

@@ -17,7 +17,7 @@ apps:unlock <app> # Unlocks an app for deployment
## Usage
### Listing Applications
### Listing applications
> New as of 0.8.1. Use the `apps` command for older versions.
@@ -33,7 +33,7 @@ node-js-app
python-app
```
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.
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:list
@@ -72,9 +72,9 @@ 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
- Configure domain names and SSL certificates.
- Create and link datastores.
- Set environment variables.
### Removing a deployed app
@@ -103,7 +103,6 @@ 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
@@ -156,7 +155,7 @@ This will copy all of your app's contents into a new app directory with the name
- SSL certificates will not be copied to the new app.
- Port mappings with the scheme `https` and host-port `443` will be skipped.
> Warning: If you have exposed specific ports via docker-options, or performed anything that cannot be done against multiple applications, `apps:clone` may result in errors.
> Warning: If you have exposed specific ports via `docker-options` plugin, or performed anything that cannot be done against multiple applications, `apps:clone` may result in errors.
By default, Dokku will deploy this new application, though you can skip the deploy by using the `--skip-deploy` flag:
@@ -164,7 +163,7 @@ By default, Dokku will deploy this new application, though you can skip the depl
dokku apps:clone --skip-deploy node-js-app io-js-app
```
Finally, if the application already exists, you may wish to ignore errors resulting from attempting to clone over it. To do so, you can use the `--ignore-existing` flag. A warning will be emitted, but the command will return 0.
Finally, if the application already exists, you may wish to ignore errors resulting from attempting to clone over it. To do so, you can use the `--ignore-existing` flag. A warning will be emitted, but the command will return `0`.
```shell
dokku apps:clone --ignore-existing node-js-app io-js-app
@@ -191,7 +190,7 @@ dokku apps:lock node-js-app
In some cases, it may be necessary to remove an existing deploy lock. This can be performed via the `apps:unlock` command.
> Warning: Removing the deploy lock _will not_ stop in progress deploys. At this time, in progress deploys will need to be manually terminated by someone with server access.
> Warning: Removing the deploy lock *will not* stop in progress deploys. At this time, in progress deploys will need to be manually terminated by someone with server access.
```shell
dokku apps:unlock node-js-app

5
docs/deployment/logs.md
View File

@@ -7,7 +7,7 @@ logs:failed [<app>] # Shows the last failed deploy
## Usage
### App Logs
### Application logs
You can easily get logs of an app using the `logs` command:
@@ -31,9 +31,10 @@ You can use these modifiers as follows:
```shell
dokku logs node-js-app -t -p web
```
will show logs continually from the web process.
### Failed Deploy Logs
### Failed deploy logs
> Warning: The default `docker-local` scheduler will "store" these until the next deploy or until the old containers are garbage collected - whichever runs first. If you require the logs beyond this point in time, please ship the logs to a centralized log server.

14
docs/deployment/methods/buildpacks.md
View File

@@ -1,6 +1,6 @@
# Buildpack Deployment
Dokku normally defaults to using [heroku buildpacks](https://devcenter.heroku.com/articles/buildpacks) for deployment, though this may be overridden by committing a valid `Dockerfile` to the root of your repository and pushing the repository to your Dokku installation. To avoid this automatic `Dockerfile` deployment detection, you may do one of the following:
Dokku normally defaults to using [Heroku buildpacks](https://devcenter.heroku.com/articles/buildpacks) for deployment, though this may be overridden by committing a valid `Dockerfile` to the root of your repository and pushing the repository to your Dokku installation. To avoid this automatic `Dockerfile` deployment detection, you may do one of the following:
- Use `dokku config:set` to set the `BUILDPACK_URL` environment variable.
- Add `BUILDPACK_URL` to a committed `.env` file in the root of your repository.
@@ -17,7 +17,7 @@ dokku config:unset --no-restart node-js-app DOKKU_DOCKERFILE_CMD DOKKU_DOCKERFIL
## Specifying a custom buildpack
In certain cases you may want to specify a custom buildpack. While Dokku uses herokuish to support all the [official heroku buildpacks](https://github.com/gliderlabs/herokuish#buildpacks), it is possible that the buildpack detection does not work well for your application. As well, you may wish to use a custom buildpack to handle specific application logic.
In certain cases you may want to specify a custom buildpack. While Dokku uses Herokuish to support all the [official Heroku buildpacks](https://github.com/gliderlabs/herokuish#buildpacks), it is possible that the buildpack detection does not work well for your application. As well, you may wish to use a custom buildpack to handle specific application logic.
To use a specific buildpack, you can run the following Dokku command:
@@ -48,14 +48,14 @@ Please check the documentation for your particular buildpack(s) as you may need
## Using a specific buildpack version
As Dokku pins all buildpacks via herokuish releases, there may be occasions where a local buildpack version is out of date. If you wish to use a more recent version of the buildpack, you may use any of the above methods to specify a buildpack **without** the git sha attached like so:
As Dokku pins all buildpacks via Herokuish releases, there may be occasions where a local buildpack version is out of date. If you wish to use a more recent version of the buildpack, you may use any of the above methods to specify a buildpack *without* the Git SHA attached like so:
```shell
# using the latest nodejs buildpack
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
You may also wish to use a *specific* version of a buildpack, which is also simple
```shell
# using v87 of the nodejs buildpack
@@ -87,11 +87,11 @@ 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](/docs/deployment/process-management.md) for more details around scaling individual processes.
## Curl Build Timeouts
## 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.
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.
If you see output similar this when deploying , you may need to override the curl timeouts to increase the length of time allotted to those tasks. You can do so via the `config` plugin:
If you see output similar this when deploying , you may need to override the cURL timeouts to increase the length of time allotted to those tasks. You can do so via the `config` plugin:
```shell
dokku config:set --global CURL_TIMEOUT=1200

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

@@ -2,26 +2,26 @@
> New as of 0.3.15
While Dokku normally defaults to using [heroku buildpacks](https://devcenter.heroku.com/articles/buildpacks) for deployment, you can also use docker's native `Dockerfile` system to define a container.
While Dokku normally defaults to using [Heroku buildpacks](https://devcenter.heroku.com/articles/buildpacks) for deployment, you can also use Docker's native `Dockerfile` system to define a container.
> Dockerfile support is considered a **Power User** feature. By using Dockerfile-based deployment, you agree that you will not have the same comfort as that enjoyed by Buildpack users, and Dokku features may work differently. Differences between the two systems will be documented here.
> Dockerfile support is considered a *power user* feature. By using Dockerfile-based deployment, you agree that you will not have the same comfort as that enjoyed by buildpack users, and Dokku features may work differently. Differences between the two systems will be documented here.
To use a dockerfile for deployment, commit a valid `Dockerfile` to the root of your repository and push the repository to your Dokku installation. If this file is detected, Dokku will default to using it to construct containers **except** in the following two cases:
To use a Dockerfile for deployment, commit a valid `Dockerfile` to the root of your repository and push the repository to your Dokku installation. If this file is detected, Dokku will default to using it to construct containers *except* in the following two cases:
- The application has a `BUILDPACK_URL` environment variable set via the `dokku config:set` command or in a committed `.env` file. In this case, Dokku will use your specified buildpack.
- The application has a `.buildpacks` file in the root of the repository. In this case, Dokku will use your specified buildpack(s).
## Switching from Buildpack deployments
## Switching from buildpack deployments
If an application was previously deployed via Buildpacks, the following commands should be run before a Dockerfile deploy will succeed:
If an application was previously deployed via buildpacks, the following commands should be run before a Dockerfile deploy will succeed:
```shell
dokku config:unset --no-restart node-js-app DOKKU_PROXY_PORT_MAP
```
## Build-time Configuration Variables
## Build-time configuration variables
For security reasons - and as per [docker recommendations](https://github.com/docker/docker/issues/13490) - Dockerfile-based deploys have variables available only during runtime.
For security reasons - and as per [Docker recommendations](https://github.com/docker/docker/issues/13490) - Dockerfile-based deploys have variables available only during runtime.
For users that require customization in the `build` phase, you may use build arguments via the [docker-options plugin](docs/advanced-usage/docker-options.md):
@@ -61,7 +61,7 @@ RUN echo $NODE_ENV
## Customizing the run command
By default no arguments are passed to `docker run` when deploying the container and the `CMD` or `ENTRYPOINT` defined in the `Dockerfile` are executed. You can take advantage of docker ability of overriding the `CMD` or passing parameters to your `ENTRYPOINT` setting `$DOKKU_DOCKERFILE_START_CMD`. Let's say for example you are deploying a base nodejs image, with the following `ENTRYPOINT`:
By default no arguments are passed to `docker run` when deploying the container and the `CMD` or `ENTRYPOINT` defined in the `Dockerfile` are executed. You can take advantage of docker ability of overriding the `CMD` or passing parameters to your `ENTRYPOINT` setting `$DOKKU_DOCKERFILE_START_CMD`. Let's say for example you are deploying a base Node.js image, with the following `ENTRYPOINT`:
```Dockerfile
ENTRYPOINT ["node"]
@@ -73,18 +73,17 @@ You can do:
dokku config:set node-js-app DOKKU_DOCKERFILE_START_CMD="--harmony server.js"
```
To tell docker what to run.
To tell Docker what to run.
Setting `$DOKKU_DOCKERFILE_CACHE_BUILD` to `true` or `false` will enable or disable docker's image layer cache. Lastly, for more granular build control, you may also pass any `docker build` option to `docker`, by setting `$DOKKU_DOCKER_BUILD_OPTS`.
Setting `$DOKKU_DOCKERFILE_CACHE_BUILD` to `true` or `false` will enable or disable Docker's image layer cache. Lastly, for more granular build control, you may also pass any `docker build` option to `docker`, by setting `$DOKKU_DOCKER_BUILD_OPTS`.
### Procfiles and Multiple Processes
### Procfiles and multiple processes
> New as of 0.5.0
You can also customize the run command using a `Procfile`, much like you would on Heroku or
with a buildpack deployed app. The `Procfile` should contain one or more lines defining [process
types and associated commands](https://devcenter.heroku.com/articles/procfile#declaring-process-types).
When you deploy your app a Docker image will be built, the `Procfile` will be extracted from the image
with a buildpack deployed app. The `Procfile` should contain one or more lines defining [process types and associated commands](https://devcenter.heroku.com/articles/procfile#declaring-process-types).
When you deploy your app, a Docker image will be built. The `Procfile` will be extracted from the image
(it must be in the folder defined in your `Dockerfile` as `WORKDIR` or `/app`) and the commands
in it will be passed to `docker run` to start your process(es). Here's an example `Procfile`:

18
docs/deployment/methods/git.md
View File

@@ -1,4 +1,4 @@
# GIT Deployment
# Git Deployment
> Subcommands new as of 0.12.0
@@ -8,11 +8,11 @@ git:report [<app>] [<flag>] # Displays a git report for one or more
git:set <app> <key> (<value>) # Set or clear a git property for an app
```
GIT-based deployment has been the traditional method of deploying applications in Dokku. As of v0.12.0, Dokku introduces a few ways to customize the experience of deploying via `git push`. A GIT-based deployment currently supports building applications via both [Buildpack](/docs/deployment/methods/buildpacks.md) and [Dockerfile](/docs/deployment/methods/dockerfiles.md).
Git-based deployment has been the traditional method of deploying applications in Dokku. As of v0.12.0, Dokku introduces a few ways to customize the experience of deploying via `git push`. A Git-based deployment currently supports building applications via both [Buildpack](/docs/deployment/methods/buildpacks.md) and [Dockerfile](/docs/deployment/methods/dockerfiles.md).
## Usage
### Initializing an Application
### Initializing an application
When an application is created via `git push`, Dokku will create the proper `pre-receive` hook in order to execute the build pipeline. In certain cases - such as when fronting deploys with the [`git-http-backend`](https://git-scm.com/docs/git-http-backend) - this may not be correctly created. As an alternative, the `git:initialize` command can be used to trigger this creation:
@@ -23,13 +23,13 @@ When an application is created via `git push`, Dokku will create the proper `pre
dokku git:initialize node-js-app
```
In order for the above command to succeed, the application _must_ already exist.
In order for the above command to succeed, the application *must* already exist.
> Warning: If the pre-receive hook was customized in any way, this will overwrite that hook with the current defaults for Dokku.
> Warning: If the `pre-receive` hook was customized in any way, this will overwrite that hook with the current defaults for Dokku.
### Changing the Deploy Branch
### Changing the deploy branch
By default, Dokku will deploy code pushed to the `master` branch. In order to quickly deploy a different local branch, the following GIT command can be used:
By default, Dokku will deploy code pushed to the `master` branch. In order to quickly deploy a different local branch, the following Git command can be used:
```shell
# on the local machine
@@ -53,11 +53,11 @@ dokku git:set node-js-app deploy-branch SOME_BRANCH_NAME
Pushing multiple branches can also be supported by creating a [receive-branch](/docs/development/plugin-triggers.md#receive-branch) plugin trigger in a custom plugin.
### Configuring the GIT_REV Environment Variable
### Configuring the `GIT_REV` environment variable
> New as of 0.12.0
Application deployments will include a special `GIT_REV` environment variable containing the current deployment sha being deployed. For rebuilds, this sha will remain the same.
Application deployments will include a special `GIT_REV` environment variable containing the current deployment sha being deployed. For rebuilds, this SHA will remain the same.
To configure the name of the `GIT_REV` environment variable, run the `git:set` command as follows:

36
docs/deployment/methods/images.md
View File

@@ -9,14 +9,14 @@ tags:deploy <app> <tag> # Deploy tagged app image
tags:destroy <app> <tag> # Remove app image tag
```
The Dokku tags plugin allows you to add docker image tags to the currently deployed app image for versioning and subsequent deployment.
The Dokku tags plugin allows you to add Docker image tags to the currently deployed app image for versioning and subsequent deployment.
> When triggering `dokku ps:rebuild APP` on an application deployed via the `tags` plugin, the following may occur:
>
> - Applications previously deployed via another method (`git`/`tar`): The application may revert to a state before the latest custom image tag was deployed.
> - Applications that were only ever deployed via the `tags` plugin: No action will be taken against your application.
>
> Please use the `tags:deploy` command when redeploying an application deployed via docker image.
> Please use the `tags:deploy` command when redeploying an application deployed via Docker image.
## Usage
@@ -40,7 +40,7 @@ dokku/node-js-app latest 936a42f25901 About a minute ago
### Creating a tag
You can also create new tags for that app using the `tags:create` function. Tags should conform to the docker tagging specification for your docker version. As of 1.10, that specification is available [here](https://github.com/docker/docker/blob/master/image/spec/v1.1.md), while users of older versions can check the documentation [here](https://github.com/docker/docker/blob/master/image/spec/v1.md).
You can also create new tags for that app using the `tags:create` function. Tags should conform to the Docker tagging specification for your Docker version. As of 1.10, that specification is available [here](https://github.com/docker/docker/blob/master/image/spec/v1.1.md), while users of older versions can check the documentation [here](https://github.com/docker/docker/blob/master/image/spec/v1.md).
```shell
dokku tags:create node-js-app v1
@@ -67,7 +67,7 @@ dokku/node-js-app v1 936a42f25901 About a minute ago
Finally, you can also deploy a local image using the `tags:deploy` command. When specifying a tag that is not `latest`, the released image will be retagged as the `latest` image tag for the app.
> Warning: For images based on herokuish, using the `tags:deploy` command will reset environment variables written into the image, causing a retag to occur. This will - on average - add two extra layers to your deployed image. Note that this does not affect dockerfile-based images, which are the majority of images deployed via the `tags` command.
> Warning: For images based on Herokuish, using the `tags:deploy` command will reset environment variables written into the image, causing a retag to occur. This will - on average - add two extra layers to your deployed image. Note that this does not affect Dockerfile-based images, which are the majority of images deployed via the `tags` command.
```shell
dokku tags:deploy node-js-app v1
@@ -100,31 +100,31 @@ dokku tags:deploy node-js-app v1
http://node-js-app.dokku.me
```
## Image Workflows
## Image workflows
### Deploying from a Docker Registry
### Deploying from a Docker registry
You can alternatively add image pulled from a docker Registry and deploy app from it by using tagging feature. In this example, we are deploying from Docker Hub.
You can alternatively add image pulled from a Docker registry and deploy from it by using tagging feature. In this example, we are deploying from Docker Hub.
1. Create Dokku app as usual
1. Create Dokku app as usual.
```shell
dokku apps:create test-app
```
2. Pull image from Docker Hub
2. Pull image from Docker Hub.
```shell
docker pull demo-repo/some-image:v12
```
3. Retag the image to match the created app
3. Retag the image to match the created app.
```shell
docker tag demo-repo/some-image:v12 dokku/test-app:v12
```
4. Deploy tag
4. Deploy tag.
```shell
dokku tags:deploy test-app v12
@@ -137,22 +137,22 @@ artifacts in your repository. For some projects however, building artifacts duri
to Dokku may affect the performance of running applications.
One solution is to build a finished Docker image on a CI service (or even locally) and deploy
it directly to the host running dokku.
it directly to the host running Dokku.
1. Build image on CI (or locally)
1. Build image on CI (or locally).
```shell
docker build -t dokku/test-app:v12 .
# Note: The image must be tagged `dokku/<app-name>:<version>`
```
2. Deploy image to Dokku host
2. Deploy image to Dokku host.
```shell
docker save dokku/test-app:v12 | ssh my.dokku.host "docker load | dokku tags:deploy test-app v12"
```
> Note: You can also use a Docker Registry to push and pull
> Note: You can also use a Docker registry to push and pull
> the image rather than uploading it directly.
Here's a more complete example using the above method:
@@ -167,6 +167,6 @@ ssh my.dokku.host "dokku tags:create test-app previous; dokku tags:deploy test-a
```
## Related articles
- [Setting up Persistent Storage](/docs/advanced-usage/persistent-storage.md)
- [Defining Environment Variables](/docs/configuration/environment-variables.md)
- [Setting up the Ports](/docs/advanced-usage/proxy-management.md)
- [Setting up persistent storage](/docs/advanced-usage/persistent-storage.md)
- [Defining environment variables](/docs/configuration/environment-variables.md)
- [Setting up the ports](/docs/advanced-usage/proxy-management.md)

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

@@ -18,7 +18,7 @@ tar:in <app> # Reads an tarball containing the
### 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.
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.

26
docs/deployment/one-off-processes.md
View File

@@ -61,7 +61,7 @@ dokku --rm run node-js-app some-command
dokku --rm-container run node-js-app some-command
```
For tasks that should not be interrupted, run is the **preferred** method of handling cron tasks, as the container will continue running even during a deploy or scaling event. The trade-off is that there will be an increase in memory usage if there are multiple concurrent tasks running.
For tasks that should not be interrupted, run is the *preferred* method of handling cron tasks, as the container will continue running even during a deploy or scaling event. The trade-off is that there will be an increase in memory usage if there are multiple concurrent tasks running.
## Entering existing containers
@@ -79,7 +79,7 @@ dokku enter node-js-app web.1
dokku enter node-js-app --container-id ID
```
Additionally, you can run `enter` with no container-type. If only a single container-type is defined in your app, you will be dropped into the only running container. This behavior is not supported when specifying a custom command; as described below.
Additionally, you can run `enter` with no `<container-type>`. If only a single `<container-type>` is defined in your app, you will be dropped into the only running container. This behavior is not supported when specifying a custom command; as described below.
By default, it runs a `/bin/bash`, but can also be used to run a custom command:
@@ -93,7 +93,7 @@ dokku enter node-js-app web python script/background-worker.py
### Using `enter` for cron tasks
Your procfile can have the following entry:
Your Procfile can have the following entry:
```Procfile
cron: sleep infinity
@@ -113,28 +113,28 @@ dokku enter node-js-app cron some-command
Note that you can also run multiple commands at the same time to reduce memory usage, though that may result in polluting the container environment.
For tasks that will properly resume, you **should** use the above method, as running tasks will be interrupted during deploys and scaling events, and subsequent commands will always run with the latest container. Note that if you scale the cron container down, this may interrupt proper running of the task.
For tasks that will properly resume, you *should* use the above method, as running tasks will be interrupted during deploys and scaling events, and subsequent commands will always run with the latest container. Note that if you scale the cron container down, this may interrupt proper running of the task.
## General Cron Recommendations
## General cron recommendations
Regularly scheduled tasks can be a bit of a pain with dokku. The following are general recommendations to follow to help ensure successful task runs.
Regularly scheduled tasks can be a bit of a pain with Dokku. The following are general recommendations to follow to help ensure successful task runs.
- Use the `dokku` user's crontab
- If you do not, the `dokku` binary will attempt to execute with `sudo` dokku, and your cron run with fail with `sudo: no tty present and no askpass program specified`
- Use the `dokku` user's crontab.
- If you do not, the `dokku` binary will attempt to execute with `sudo`, and your cron run with fail with `sudo: no tty present and no askpass program specified`.
- Add a `MAILTO` environment variable to ship cron emails to yourself.
- Add a `PATH` environment variable or specify the full path to binaries on the host.
- Add a `SHELL` environment variable to specify bash when running commands.
- Add a `SHELL` environment variable to specify Bash when running commands.
- Keep your cron tasks in time-sorted order.
- Keep your server time in UTC so you don't need to translate daylight saving's time when reading the cronfile.
- Keep your server time in UTC so you don't need to translate daylight savings time when reading the cronfile.
- Run tasks at the lowest traffic times if possible.
- Use cron to **trigger** jobs, not run them. Use a real queuing system such as rabbitmq to actually process jobs.
- Use cron to *trigger* jobs, not run them. Use a real queuing system such as rabbitmq to actually process jobs.
- Try to keep tasks quiet so that mails only send on errors.
- Do not silence standard error or standard out. If you silence the former, you will miss failures. Silencing the latter means you should actually make application changes to handle log levels.
- Use a service such as [Dead Man's Snitch](https://deadmanssnitch.com) to verify that cron tasks completed successfully.
- Add lots of comments to your cronfile, including what a task is doing, so that you don't spend time deciphering the file later.
- Place your cronfiles in a pattern such as `/etc/cron.d/APP`.
- Do not use non-ascii characters in your cronfile names. Cron is finicky.
- Remember to have trailing newlines in your cronfile! Cron is finicky.
- Do not use non-ASCII characters in your cronfile names. cron is finicky.
- Remember to have trailing newlines in your cronfile! cron is finicky.
The following is a sample cronfile that you can use for your applications:

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

@@ -21,7 +21,7 @@ ps:stopall # Stop all app container(s)
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](/docs/deployment/process-management.md#manually-managing-process-scaling).
> 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.
> 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.
## Usage
@@ -47,7 +47,7 @@ This command will gather all the running container IDs for your application and
### Rebuilding applications
There are some Dokku commands which will not automatically rebuild an application's environment, or which can be told to skip a rebuild. For instance, you may wish to run multiple `config:set` commands without a restart so as to speed up configuration. In these cases, you can ultimately trigger an application rebuild using `ps:rebuild`
There are some Dokku commands which will not automatically rebuild an application's environment, or which can be told to skip a rebuild. For instance, you may wish to run multiple `config:set` commands without a restart so as to speed up configuration. In these cases, you can ultimately trigger an application rebuild using `ps:rebuild`
```shell
dokku ps:rebuild node-js-app
@@ -60,13 +60,13 @@ dokku ps:rebuildall
```
> The `ps:rebuild` and `ps:rebuildall` commands only work for applications for which there is a source, and thus
> will only always work deterministically for git-deployed application. Please see
> will only always work deterministically for Git-deployed application. Please see
> the [images documentation](/docs/deployment/methods/images.md) and [tar documentation](/docs/deployment/methods/tar.md)
> in for more information concerning rebuilding those applications.
### Restarting applications
Applications can be restarted, which is functionally identical to calling the `release_and_deploy` function on an application. Please not that any linked containers *must* be started before the application in order to have a successful boot.
Applications can be restarted, which is functionally identical to calling the `release_and_deploy` function on an application. Please note that any linked containers *must* be started before the application in order to have a successful boot.
```shell
dokku ps:restart node-js-app
@@ -108,7 +108,7 @@ dokku ps:scale node-js-app
### Stopping applications
Deployed applications can be stopped using the `ps:stop` command. This turns off all running containers for an application, and will result in a `502 Bad Gateway` response for the default nginx proxy implementation.
Deployed applications can be stopped using the `ps:stop` command. This turns off all running containers for an application, and will result in a **502 Bad Gateway** response for the default nginx proxy implementation.
```shell
dokku ps:stop node-js-app
@@ -130,7 +130,7 @@ dokku ps:start node-js-app
### Starting all applications
In some cases, it may be necessary to start all applications from scratch - eg. if all Docker containers have been manually stopped. This can be executed via the `ps:startall` command, which supports parallelism in the same manner `ps:rebuildall`, `ps:restartall`, and `ps:stopall` do.
In some cases, it may be necessary to start all applications from scratch - e.g. if all Docker containers have been manually stopped. This can be executed via the `ps:startall` command, which supports parallelism in the same manner `ps:rebuildall`, `ps:restartall`, and `ps:stopall` do.
Be aware that no action will be taken if the application containers are running.
@@ -138,7 +138,7 @@ Be aware that no action will be taken if the application containers are running.
dokku ps:startall
```
## Restart Policies
## Restart policies
> New as of 0.7.0
@@ -210,7 +210,7 @@ Restart policies have no bearing on server reboot, and Dokku will always attempt
## Manually managing process scaling
You can optionally _commit_ a `DOKKU_SCALE` file to the root of your repository - *not* to the /home/dokku/APP directory. Dokku expects this file to contain one line for every process defined in your Procfile.
You can optionally *commit* a `DOKKU_SCALE` file to the root of your repository - *not* to the `/home/dokku/APP` directory. Dokku expects this file to contain one line for every process defined in your Procfile.
Example:
@@ -221,4 +221,4 @@ worker=2
If it is not committed to the repository, the `DOKKU_SCALE` file will otherwise be automatically generated based on your `ps:scale` settings.
> *NOTE*: Dokku will always use the DOKKU_SCALE file that ships with the repo to override any local settings.
> *NOTE*: Dokku will always use the `DOKKU_SCALE` file that ships with the repo to override any local settings.

6
docs/deployment/remote-commands.md
View File

@@ -1,6 +1,6 @@
# Remote Commands
Dokku commands can be run over ssh. Anywhere you would run `dokku <command>`, just run `ssh -t dokku@dokku.me <command>`
Dokku commands can be run over SSH. Anywhere you would run `dokku <command>`, just run `ssh -t dokku@dokku.me <command>`
The `-t` is used to request a pty. It is highly recommended to do so.
To avoid the need to type the `-t` option each time, simply create/modify a section in the `.ssh/config` on the client side, as follows:
@@ -11,8 +11,8 @@ Host dokku.me
## Behavioral modifiers
Dokku also supports certain command-line arguments that augment it's behavior. If using these over ssh, you must use the form `ssh -t dokku@dokku.me -- <command>`
in order to avoid ssh interpretting Dokku arguments for itself.
Dokku also supports certain command line arguments that augment its behavior. If using these over SSH, you must use the form `ssh -t dokku@dokku.me -- <command>`
in order to avoid SSH interpretting Dokku arguments for itself.
```
--quiet suppress output headers

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

@@ -8,17 +8,17 @@ ssh-keys:list # List of all authorized Dokku pu
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.
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.
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.
> Users of older versions of Dokku may use the `sshcommand` binary to manage keys instead of the `ssh-keys` plugin. Please refer to the Dokku documentation for your version for more details.
## Usage
### Listing SSH Keys
### Listing SSH keys
You can use the `ssh-keys:list` command to show all configured ssh keys. Any key added via the `dokku-installer` will be associated with the `admin` key name.
You can use the `ssh-keys:list` command to show all configured SSH keys. Any key added via the `dokku-installer` will be associated with the `admin` key name.
```shell
dokku ssh-keys:list
@@ -32,11 +32,11 @@ The output contains the following information:
- SSH Key Fingerprint.
- The `KEY_NAME`.
- A comma separated list of ssh options under the `SSHCOMMAND_ALLOWED_KEYS` name.
- A comma separated list of SSH options under the `SSHCOMMAND_ALLOWED_KEYS` name.
### Adding SSH Keys
### Adding SSH keys
You can add your public key to Dokku with the `ssh-keys:add` command. The output will be the fingerprint of the ssh key:
You can add your public key to Dokku with the `ssh-keys:add` command. The output will be the fingerprint of the SSH key:
```shell
dokku ssh-keys:add KEY_NAME path/to/id_rsa.pub
@@ -48,7 +48,7 @@ b7:76:27:4f:30:90:21:ae:d4:1e:70:20:35:3f:06:d6
`KEY_NAME` is the name you want 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_NAME` is a unique name which is used to identify public keys. Attempting to re-use a key name will result in an error. The ssh (git) user is *always* `dokku`, as this is the system user that the `dokku` binary uses to perform all it's actions.
> `KEY_NAME` is a unique name which is used to identify public keys. Attempting to re-use a key name will result in an error. The SSH (Git) user is *always* `dokku`, as this is the system user that the `dokku` binary uses to perform all its actions.
Admin users and root can add keys remotely by specifying the `dokku` bin on their `ssh` command:
@@ -56,15 +56,15 @@ Admin users and root can add keys remotely by specifying the `dokku` bin on thei
cat ~/.ssh/id_rsa.pub | ssh root@dokku.me dokku ssh-keys:add 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`):
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
```
### Removing SSH Keys
### Removing SSH keys
As key names are unique, they can be used to remove a public ssh key.
As key names are unique, they can be used to remove a public SSH key.
```SHELL
dokku ssh-keys:remove KEY_NAME
@@ -76,7 +76,7 @@ Keys are given unique names, which can be used in conjunction with the [user-aut
## Granting other Unix user accounts Dokku access
Any Unix user account which belongs to the 'sudo' Unix group can run Dokku. However, you may want to give them Dokku access but not full sudo privileges.
Any Unix user account which belongs to the `sudo` Unix group can run Dokku. However, you may want to give them Dokku access but not full sudo privileges.
To allow other Unix user accounts to be able to run Dokku commands, without giving them full sudo access, modify your sudoers configuration.

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

@@ -11,7 +11,7 @@ checks:run <app> [process-type(s)] Runs zero-downtime checks for all proce
checks:skip <app> [process-type(s)] Skip zero-downtime checks for all processes (or comma-separated process-type list)
```
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.
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.
@@ -19,17 +19,17 @@ You may both create user-defined checks for web processes using a `CHECKS` file,
> as the Django framework - checks for specific hostnames or header values, these
> checks will fail. To avoid this:
>
> - Remove such checks from your code: Modify your application to remove the hostname check completely
> - Allow checks from all hostnames: Modify your application to accept a dynamically provided hostname
> - Specify the domain within the check: See below for further documentation
> - Remove such checks from your code: Modify your application to remove the hostname check completely.
> - Allow checks from all hostnames: Modify your application to accept a dynamically provided hostname.
> - Specify the domain within the check: See below for further documentation.
## Configuring Check Settings using the `config` 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.
- `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.
@@ -56,7 +56,7 @@ dokku checks:skip node-js-app worker,web
DOKKU_CHECKS_SKIPPED: worker,web
```
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.
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
@@ -110,22 +110,22 @@ You can pass flags which will output only the value of the specific information
dokku checks:report node-js-sample --checks-disabled-list
```
## Customizing 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.
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
- 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.
> 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
### Check instructions
The format of a check instruction is a path or relative URL, optionally followed by the expected content:
@@ -156,9 +156,9 @@ https://admin.dokku.me Admin Dashboard
https://static.dokku.me/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.
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
### 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.
@@ -172,7 +172,7 @@ ATTEMPTS=10 # Attempt checks 10 times
/ My Amazing App
```
## Manually Invoking Checks
## 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.
@@ -220,7 +220,7 @@ dokku checks:run node-js-app worker
-----> Default container check successful!
```
An app process id may also be specified:
An app process ID may also be specified:
```shell
dokku checks:run node-js-app web.2
@@ -247,7 +247,7 @@ dokku checks:run node-js-app non-existent
Invalid process type specified (APP.non-existent)
```
Non-existent process ids will *also* result in an error
Non-existent process IDs will *also* result in an error
```shell
dokku checks:run node-js-app web.3
@@ -258,11 +258,11 @@ dokku checks:run node-js-app web.3
Invalid container id specified (APP.web.3)
```
## Example: Successful Rails Deployment
## 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.
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
### `CHECKS` file
```
WAIT=10
@@ -276,9 +276,9 @@ For this check to work, we've added a line to `config/routes.rb` that simply ret
get '/check.txt', to: proc {[200, {}, ['simple_check']]}
```
### Deploy Output
### Deploy output
> Note: The output has been trimmed for brevity
> Note: The output has been trimmed for brevity.
```shell
git push dokku master
@@ -334,13 +334,13 @@ curl: (7) Failed to connect to 172.17.0.155 port 5000: Connection refused
http://myapp.dokku.me
```
## Example: Failing Rails Deployment
## 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 PostgreSQL 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 PostgreSQL database connection failure.
Once the attempts have been exceeded, the deployment fails and we see the container output, which shows the Postgres connection errors.
Once the attempts have been exceeded, the deployment fails and we see the container output, which shows the PostgreSQL connection errors.
### CHECKS file
### `CHECKS` file
```
WAIT=10
@@ -348,11 +348,11 @@ ATTEMPTS=6
/
```
> The check to the root url '/' would normally access the database.
> The check to the root url `/` would normally access the database.
### Deploy Output
### Deploy output
> Note: The output has been trimmed for brevity
> Note: The output has been trimmed for brevity.
```shell
git push dokku master

2
docs/template.html
View File

@@ -121,7 +121,7 @@
<a href="/{{NAME}}/deployment/application-management/" class="list-group-item">Application Management</a>
<a href="/{{NAME}}/deployment/logs/" class="list-group-item">Application Logs</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/one-off-processes/" class="list-group-item">One-Off Processes/Cron</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>