Deployment Tasks
New
Introduced in 0.5.0
Usage
Overview
Sometimes you need to run a command on deployment time, but before an app is completely deployed. Common use cases include:
- Checking a database is initialized
- Running database migrations
- Any commands required to set up the server (e.g. something like a Django
collectstatic)
To support this, Dokku provides support for a special release command within your app's Procfile, as well as a special scripts.dokku key inside of your app's app.json file. Be aware that all commands are run within the context of the built docker image - no commands affect the host unless there are volume mounts attached to your app.
Each "phase" has different expectations and limitations:
app.json:scripts.dokku.predeploy- When to use: This should be used if your app does not support arbitrary build commands and you need to make changes to the built image.
- Are changes committed to the image at this phase: Yes
- Example use-cases
- Bundling assets in a slightly different way
- Installing a custom package from source or copying a binary into place
app.json:scripts.dokku.postdeploy- When to use: This should be used in conjunction with external systems to signal the completion of your deploy.
- Are changes committed to the image at this phase: No
- Example use-cases
- Notifying slack that your app is deployed
- Coordinating traffic routing with a central load balancer
app.json:scripts.postdeploy- When to use: This should be used when you wish to run a command once, after the app is created and not on subsequent deploys to the app.
- Are changes committed to the image at this phase: No
- Example use-cases
- Setting up OAuth clients and DNS
- Loading seed/test data into the app’s test database
Procfile:release- When to use: This should be used in conjunction with external systems to signal the completion of your app image build.
- Are changes committed to the image at this phase: No
- Example use-cases
- Sending CSS, JS, and other assets from your app’s slug to a CDN or S3 bucket
- Priming or invalidating cache stores
- Running database migrations
Additionally, if using a Dockerfile with an ENTRYPOINT, the deployment task is passed to that entrypoint as is. The exceptions are if the entrypoint is one of the following:
["/tini", "--"]["/bin/tini", "--"]["/usr/bin/tini", "--"]["/usr/local/bin/tini", "--"]
Please keep the above in mind when utilizing deployment tasks.
Info
To execute commands on the host during a release phase, see the plugin creation documentation docs for more information on building your own custom plugin.
Changing the app.json location
When deploying a monorepo, it may be desirable to specify the specific path of the app.json file to use for a given app. This can be done via the app-json:set command. If a value is specified and that file does not exist within the repository, Dokku will continue the build process as if the repository has no app.json file.
The default value may be set by passing an empty value for the option:
The appjson-path property can also be set globally. The global default is app.json, and the global value is used when no app-specific value is set.
The default value may be set by passing an empty value for the option.
Displaying app-json reports for an app
New
Introduced in 0.25.0
You can get a report about the app's storage status using the app-json:report command:
=====> node-js-app app-json information
App-json computed appjson path: app2.json
App-json global appjson path: app.json
App-json appjson path: app2.json
=====> python-sample app-json information
App-json computed appjson path: app.json
App-json global appjson path: app.json
App-json appjson path:
=====> ruby-sample app-json information
App-json computed appjson path: app.json
App-json global appjson path: app.json
App-json appjson path:
You can run the command for a specific app also.
You can pass flags which will output only the value of the specific information you want. For example:
Deployment tasks
app.json deployment tasks
Dokku provides limited support for the app.json manifest from Heroku (documentation available here). The keys available for use with Deployment Tasks are:
scripts.dokku.predeploy: This is run after an app's docker image is built, but before any containers are scheduled. Changes made to your image are committed at this phase.scripts.dokku.postdeploy: This is run after an app's containers are scheduled. Changes made to your image are not committed at this phase.scripts.postdeploy: This is run after an app's containers are scheduled. Changes made to your image are not committed at this phase.
For buildpack-based deployments, the location of the app.json file should be at the root of your repository. Dockerfile-based app deploys should have the app.json in the configured WORKDIR directory; otherwise Dokku defaults to the buildpack app behavior of looking in /app.
Warning
Any failed app.json deployment task will fail the deploy. In the case of either phase, a failure will not affect any running containers.
The following is an example app.json file. Please note that only the scripts.dokku.predeploy and scripts.dokku.postdeploy tasks are supported by Dokku at this time. All other fields will be ignored and can be omitted.
{
"scripts": {
"dokku": {
"predeploy": "touch /app/predeploy.test",
"postdeploy": "curl https://some.external.api.service.com/deployment?state=success"
},
"postdeploy": "curl https://some.external.api.service.com/created?state=success"
}
}
Procfile Release command
New
Introduced in 0.14.0
The Procfile also supports a special release command which acts in a similar way to the Heroku Release Phase. This command is executed after an app's docker image is built, but before any containers are scheduled. This is also run after any command executed by scripts.dokku.predeploy.
To use the release command, simply add a release stanza to your Procfile.
Unlike the scripts.dokku.predeploy command, changes made during by the release command are not persisted to disk.