From 76e9ea6cc3268dcf73657ad279b26eb013ea8121 Mon Sep 17 00:00:00 2001 From: Marc Diethelm Date: Sun, 15 Nov 2015 12:18:35 +0100 Subject: [PATCH 1/5] Improve docker-options.md - Add note to avoid problems with shared volumes permissions - Restructure the doc to help comprehension - Make command examples consistent - Improve wording in some places - Advanced usage: remove "avoid if possible". It made little sense. - docker (project) --> Docker - dokku (project) --> Dokku - dokku (command) --> `dokku` - add `shell` to code blocks --- docs/docker-options.md | 75 +++++++++++++++++++++++------------------- 1 file changed, 42 insertions(+), 33 deletions(-) diff --git a/docs/docker-options.md b/docs/docker-options.md index dfb1f9e83..e648756b8 100644 --- a/docs/docker-options.md +++ b/docs/docker-options.md @@ -2,49 +2,58 @@ > New as of 0.3.17 -``` -docker-options Display apps docker options for all phases -docker-options Display apps docker options for phase (comma-separated phase list) -docker-options:add OPTION Add docker option to app for phase (comma-separated phase list) -docker-options:remove OPTION Remove docker option from app for phase (comma-separated phase list) -``` - -Add some options (first, for the deployed/running app and second when executing `dokku run`): - -``` -dokku docker-options:add myapp deploy "-v /host/path:/container/path" -dokku docker-options:add myapp run "-v /another/container/path" -``` - -Check what we added +Pass [options](http://docs.docker.io/en/latest/reference/run/) to Docker during Dokku build, deploy and run phases ```shell -dokku docker-options myapp -# Deploy options: -# -v /host/path:/container/path -# Run options: -# -v /another/container/path +docker-options Display app's Docker options for all phases +docker-options Display app's Docker options for phase (comma-separated phase list) +docker-options:add OPTION Add Docker option to app for phase (comma-separated phase list) +docker-options:remove OPTION Remove Docker option from app for phase (comma-separated phase list) ``` -Remove an option +## About `dokku` phases -```shell -dokku docker-options:remove myapp run "--link container_name:alias" -``` - -### Note about `dokku` phases and `docker-options` - -`dokku` deploys your application in multiple "phases" and the `docker-options` plugin allows you to pass arguments to the underlying docker container in the following 3 phases/containers: +Dokku deploys your application in multiple "phases" and the `docker-options` plugin allows you to pass arguments to their underlying docker container: - `build`: the container that executes the appropriate buildpack - `deploy`: the container that executes your running/deployed application - `run`: the container that executes any arbitrary command via `dokku run myapp` -## Advanced Usage (avoid if possible) +## Examples -In your applications folder (`/home/dokku/app_name`) create a file called `DOCKER_OPTIONS_RUN` (or `DOCKER_OPTIONS_BUILD` or `DOCKER_OPTIONS_DEPLOY`). +### Add Docker options -Inside this file list one docker option per line. For example: +Add some options for the deployed/running app and when executing `dokku run`: + +```shell +# Mount a host volume in a Docker container: "-v /host/path:/container/path" +dokku docker-options:add myapp deploy "-v /home/dokku/logs/myapp:/app/logs" +dokku docker-options:add myapp run "-v /home/dokku/logs/myapp:/app/logs" +``` + +> Note: When [mounting a host directory](https://docs.docker.com/engine/reference/run/#volume-shared-filesystems) in a Dokku app you should first create that directory as user `dokku` and then mount the directory under `/app` in the container using `docker-options` as above. Else the app will lack write permission in the directory. + +### Output Docker options + +```shell +dokku docker-options myapp +# Deploy options: +# -v /home/dokku/logs/myapp:/app/logs +# Run options: +# -v /home/dokku/logs/myapp:/app/logs +``` + +### Remove a Docker option + +```shell +dokku docker-options:remove myapp run "-v /home/dokku/logs/myapp:/app/logs" +``` + +## Advanced usage + +In your applications folder `/home/dokku/app_name` create a file called `DOCKER_OPTIONS_RUN` (or `DOCKER_OPTIONS_BUILD` or `DOCKER_OPTIONS_DEPLOY`). + +Inside this file list one Docker option per line. For example: ```shell --link container_name:alias @@ -52,7 +61,7 @@ Inside this file list one docker option per line. For example: -v /another/container/path ``` -The above example will result in the following options being passed to docker during `dokku run`: +The above example will result in the following options being passed to Docker during `dokku run`: ```shell --link container_name:alias -v /host/path:/container/path -v /another/container/path @@ -60,4 +69,4 @@ The above example will result in the following options being passed to docker du You may also include comments (lines beginning with a #) and blank lines in the DOCKER_OPTIONS file. -Move information on docker options can be found here: http://docs.docker.io/en/latest/reference/run/ . +Move information on Docker options can be found here: http://docs.docker.io/en/latest/reference/run/ . From 06b8d166ca0e6f25feab84f616e70ad2d3cd49d1 Mon Sep 17 00:00:00 2001 From: Marc Diethelm Date: Sun, 15 Nov 2015 12:22:40 +0100 Subject: [PATCH 2/5] Small improvements to doc --- docs/docker-options.md | 8 ++++---- 1 file changed, 4 insertions(+), 4 deletions(-) diff --git a/docs/docker-options.md b/docs/docker-options.md index e648756b8..631394df3 100644 --- a/docs/docker-options.md +++ b/docs/docker-options.md @@ -2,16 +2,16 @@ > New as of 0.3.17 -Pass [options](http://docs.docker.io/en/latest/reference/run/) to Docker during Dokku build, deploy and run phases +Pass [options](http://docs.docker.io/en/latest/reference/run/) to Docker during Dokku's build, deploy and run phases -```shell +``` docker-options Display app's Docker options for all phases docker-options Display app's Docker options for phase (comma-separated phase list) docker-options:add OPTION Add Docker option to app for phase (comma-separated phase list) docker-options:remove OPTION Remove Docker option from app for phase (comma-separated phase list) ``` -## About `dokku` phases +## About Dokku phases Dokku deploys your application in multiple "phases" and the `docker-options` plugin allows you to pass arguments to their underlying docker container: @@ -23,7 +23,7 @@ Dokku deploys your application in multiple "phases" and the `docker-options` plu ### Add Docker options -Add some options for the deployed/running app and when executing `dokku run`: +Add some options for the deployed/running app and when executing [`dokku run`](deployment/one-off-processes/): ```shell # Mount a host volume in a Docker container: "-v /host/path:/container/path" From 200d1128a1c8e307d424e1a17d597802d58142d1 Mon Sep 17 00:00:00 2001 From: Marc Diethelm Date: Sun, 15 Nov 2015 22:50:24 +0100 Subject: [PATCH 3/5] Update docker-options plugin help for consistency with help docs --- plugins/docker-options/commands | 8 ++++---- 1 file changed, 4 insertions(+), 4 deletions(-) diff --git a/plugins/docker-options/commands b/plugins/docker-options/commands index 77b1a12a6..c9661756c 100755 --- a/plugins/docker-options/commands +++ b/plugins/docker-options/commands @@ -141,10 +141,10 @@ case "$1" in # Display usage help help | docker-options:help) cat<, Display apps docker options for all phases - docker-options , Display apps docker options for phase (comma separated phase list) - docker-options:add OPTION, Add docker option to app for phase (comma separated phase list) - docker-options:remove OPTION, Remove docker option from app for phase (comma separated phase list) + docker-options , Display app's Docker options for all phases + docker-options , Display app's Docker options for phase (comma separated phase list) + docker-options:add OPTION, Add Docker option to app for phase (comma separated phase list) + docker-options:remove OPTION, Remove Docker option from app for phase (comma separated phase list) EOF ;; From 9cfa1b90653ba46838949e8cafa3ae65b96fa825 Mon Sep 17 00:00:00 2001 From: Marc Diethelm Date: Sun, 15 Nov 2015 22:51:57 +0100 Subject: [PATCH 4/5] Docs, wording: else --> otherwise --- docs/docker-options.md | 2 +- 1 file changed, 1 insertion(+), 1 deletion(-) diff --git a/docs/docker-options.md b/docs/docker-options.md index 631394df3..42d0fde9f 100644 --- a/docs/docker-options.md +++ b/docs/docker-options.md @@ -31,7 +31,7 @@ dokku docker-options:add myapp deploy "-v /home/dokku/logs/myapp:/app/logs" dokku docker-options:add myapp run "-v /home/dokku/logs/myapp:/app/logs" ``` -> Note: When [mounting a host directory](https://docs.docker.com/engine/reference/run/#volume-shared-filesystems) in a Dokku app you should first create that directory as user `dokku` and then mount the directory under `/app` in the container using `docker-options` as above. Else the app will lack write permission in the directory. +> Note: When [mounting a host directory](https://docs.docker.com/engine/reference/run/#volume-shared-filesystems) in a Dokku app you should first create that directory as user `dokku` and then mount the directory under `/app` in the container using `docker-options` as above. Otherwise the app will lack write permission in the directory. ### Output Docker options From daa3b88d91ddbcd5edcd0380321b05666b048322 Mon Sep 17 00:00:00 2001 From: Marc Diethelm Date: Sun, 15 Nov 2015 23:12:42 +0100 Subject: [PATCH 5/5] Add backticks around `build`, `deploy` and `run` --- docs/docker-options.md | 2 +- 1 file changed, 1 insertion(+), 1 deletion(-) diff --git a/docs/docker-options.md b/docs/docker-options.md index 42d0fde9f..15c5d6dda 100644 --- a/docs/docker-options.md +++ b/docs/docker-options.md @@ -2,7 +2,7 @@ > New as of 0.3.17 -Pass [options](http://docs.docker.io/en/latest/reference/run/) to Docker during Dokku's build, deploy and run phases +Pass [options](http://docs.docker.io/en/latest/reference/run/) to Docker during Dokku's `build`, `deploy` and `run` phases ``` docker-options Display app's Docker options for all phases