Mirrors/dokku
1
0
Fork 0
mirror of https://github.com/dokku/dokku.git synced 2025-12-29 00:25:08 +01:00
Code Issues Packages Projects Releases Wiki Activity

Merge pull request #7241 from dokku/7219-clarify-options-docs

Browse Source
This commit is contained in:
Jose Diaz-Gonzalez
2024-10-06 07:45:22 -04:00
committed by GitHub
parent a13a20b4e4 cf11f08698
commit d79910c0ae
1 changed files with 61 additions and 29 deletions
Download Patch File Download Diff File Expand all files Collapse all files

90
docs/advanced-usage/docker-options.md
View File

@@ -3,57 +3,89 @@
> [!IMPORTANT]
> New as of 0.3.17
Pass [container options](https://docs.docker.com/engine/reference/run/) to the `docker run` command during Dokku's `build`, `deploy` and `run` phases
```
docker-options:add <app> <phase(s)> OPTION # Add Docker option to app for phase (comma-separated phase list)
docker-options:clear <app> [<phase(s)>...] # Clear a docker options from application
docker-options:clear <app> [<phase(s)>...] # Clear a docker options from app
docker-options:remove <app> <phase(s)> OPTION # Remove Docker option from app for phase (comma-separated phase list)
docker-options:report [<app>] [<flag>] # Displays a docker options report for one or more apps
```
> When specifying multiple phases, they **must** be comma-separated _without_ spaces in between each phase, like so:
>
> ```shell
> dokku docker-options:add node-js-app deploy,run "-v /var/log/node-js-app:/app/logs"
> ```
The `docker-options` plugin allows users to specify custom [container options](https://docs.docker.com/engine/reference/run/) for containers created by Dokku at various phases.
## About Dokku phases
## Usage
Dokku deploys your application in multiple "phases" and the `docker-options` plugin allows you to pass arguments to their underlying docker container:
### Background
- `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`
#### Phases
Manipulation of docker options will not restart running containers. This enables multiple options to be set/unset before final application. As such, changing an app's docker options must be followed by a `dokku ps:rebuild` in order to take effect.
Dokku deploys your app in multiple "phases" and the `docker-options` plugin allows you to pass arguments to their underlying docker container:
- `build`: The `build` phase is used to provide container options that are available during the build process for use by the various builders.
- A given builder may strip out or ignore options that are unsupported by the builder in question - as an example, the `dockerfile` builder does not support mounted volumes.
- `deploy`: The `deploy` phase is used to provide container options that are set on _deployed_ process types. This covers every process type specified in an app `Procfile` as well as any default processes your app may deploy.
- The `deploy` phase is usually the correct phase to add options for
- `run`: The `run` phase is used to provide container options to one-off containers created by `dokku run`, `dokku run:detached`, and any cron tasks specified in your `app.json`.
> [!IMPORTANT]
> The `run` phase does _not_ correspond 1-to-1 to `docker run` or `docker container run` commands. Specifying a container option at the `run` phase will only be invoked on containers created by the `run` plugin and cron tasks. Please be sure to specify options at the correct phase for your use-case.
Adding or removing docker-options will not apply to any running containers, and only applies to containers created _after_ the options have been modified. As such, changing an app's docker options must be followed by a `dokku ps:rebuild` or a deploy in order to take effect.
#### Supported Docker Options
More information on supported Docker options can be found [here](https://docs.docker.com/engine/reference/commandline/run/).
Container options configured via the `docker-options` plugin are not used to modify the process a container runs. Container options are the `[OPTIONS]` portion of the following, where `[CONTAINER_COMMAND]` and `[ARG]` are the process and the arguments passed to it that are launched in the created container: `docker run [OPTIONS] [CONTAINER_COMMAND] [ARG...]`. Please see the documentation for [customizing the run command](/docs/deployment/builders/dockerfiles.md#customizing-the-run-command) or use a [Procfile](/docs/deployment/builders/dockerfiles.md#procfiles-and-multiple-processes) to modify the command used by a Dockerfile-based container.
## Examples
#### Mounting volumes and host directories
### Add Docker options
Docker supports volume and host directory mounting via the `-v` or `--volume` flags. In order to simplify usage, Dokku provides a `storage` plugin as an abstraction to interact with persistent storage. In most cases, the Dokku project recommends using the persistent storage plugin over directly manipulating docker options at different phases. See the [persistent storage documentation](/docs/advanced-usage/persistent-storage.md) for more information on how to attach persistent storage to your app.
Add some options for the deployed/running app and when executing [`dokku run`](/docs/processes/one-off-tasks.md):
### Commands
#### Add Docker options
To add a docker option to an app, use the `docker-options:add` command. This takes an app name, a comma-separated list of phases, and the docker-option to add.
```shell
# Mount a host volume in a Docker container: "-v /host/path:/container/path"
dokku docker-options:add node-js-app deploy "-v /var/log/node-js-app:/app/logs"
dokku docker-options:add node-js-app run "-v /var/log/node-js-app:/app/logs"
dokku docker-options:add node-js-app deploy "--ulimit nofile=12"
```
> [!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.
### Remove a Docker option
Multiple phases can be specified by using a comma when specifying phases:
```shell
dokku docker-options:remove node-js-app run "-v /var/log/node-js-app:/app/logs"
dokku docker-options:add node-js-app deploy,run "--ulimit nofile=12"
```
### Clear all Docker options for an app
The `docker-options:add` does not support setting multiple options in a single call. To specify multiple options, call `docker-options:add` multiple times.
```shell
dokku docker-options:add node-js-app deploy "--ulimit nofile=12"
dokku docker-options:add node-js-app deploy "--shm-size 256m"
```
#### Remove a Docker option
To remove docker options from an app, use the `docker-options:remove` command. This takes an app name, a comma-separated list of phases, and the docker-option to remove.
```shell
dokku docker-options:remove node-js-app run ""--ulimit nofile=12"
```
Multiple phases can be specified by using a comma when specifying phases:
```shell
dokku docker-options:remove node-js-app deploy,run "--ulimit nofile=12"
```
The `docker-options:remove` does not support setting multiple options in a single call. To specify multiple options, call `docker-options:remove` multiple times.
```shell
dokku docker-options:remove node-js-app deploy "--ulimit nofile=12"
dokku docker-options:remove node-js-app deploy "--shm-size 256m"
```
#### Clear all Docker options for an app
Docker options can be removed for a specific app using the `docker-options:clear` command.
@@ -84,7 +116,7 @@ dokku docker-options:clear node-js-app build,run
-----> Clearing docker-options for node-js-app on phase run
```
### Displaying docker-options reports for an app
#### Displaying docker-options reports for an app
> [!IMPORTANT]
> New as of 0.8.1
@@ -98,8 +130,8 @@ dokku docker-options:report
```
=====> node-js-app docker options information
Docker options build:
Docker options deploy: -v /var/log/node-js-app:/app/logs
Docker options run: -v /var/log/node-js-app:/app/logs
Docker options deploy: --ulimit nofile=12 --shm-size 256m
Docker options run: --ulimit nofile=12 --shm-size 256m
=====> python-sample docker options information
Docker options build:
Docker options deploy: