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

Fix Deployment guides style

Browse Source
This commit is contained in:
Jay Jun
2019-02-19 20:01:24 +08:00
parent 42b6876f2c
commit e839c29916
14 changed files with 142 additions and 143 deletions
Download Patch File Download Diff File Expand all files Collapse all files

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.