8.7 KiB
app.json
app.json is a manifest format for describing web apps. It declares cron tasks, healthchecks, and other information required to run an app on Dokku. This document describes the schema in detail.
Important
While the
app.jsonformat used by Dokku is based on the one supported by Heroku, not all Heroku functionality is supported by Dokku.
Buildpacks
{
"buildpacks": [
{
"url": "heroku/python"
},
{
"url": "https://github.com/heroku/heroku-buildpack-nodejs.git"
}
]
}
(list, optional) A list of buildpacks to use when deploying the app. Each entry is an object with a url property. Buildpacks specified via the buildpacks:add or buildpacks:set commands take precedence over those specified in app.json. Buildpack URLs may use the shorthand format (e.g., heroku/python) which will be expanded to the full GitHub URL.
url: (string, required) The URL or shorthand reference of the buildpack.
Cron
{
"cron": [
{
"command": "echo 'hello'",
"schedule": "0 1 * * *"
}
]
}
(list, optional) A list of cron resources. Keys are the names of the process types. The values are an object containing one or more of the following properties:
command: (string, required)maintenance: (boolean, optional)schedule: (string, required)concurrency_policy: (string, optional, default:allow, options:allow,forbid,replace)
Env
{
"env": {
"SIMPLE_VAR": "default_value",
"SECRET_KEY": {
"description": "A secret key for signing tokens",
"generator": "secret"
},
"DATABASE_URL": {
"description": "PostgreSQL connection string",
"required": true
},
"OPTIONAL_VAR": {
"description": "An optional configuration value",
"value": "default",
"required": false
},
"SYNC_VAR": {
"description": "A variable that updates on every deploy",
"value": "synced_value",
"sync": true
}
}
}
(object, optional) A key-value object for environment variable configuration. Keys are the variable names. Values can be either a string (used as the default value) or an object with the following properties:
description: (string, optional) Human-readable explanation of the variable's purposevalue: (string, optional) Default value for the variablerequired: (boolean, optional, default:true) Whether the variable must have a valuegenerator: (string, optional) Function to generate the value. Currently only"secret"is supported, which generates a 64-character cryptographically secure hex stringsync: (boolean, optional, default:false) Iftrue, the value will be set on every deploy, overwriting any existing value
Behavior
Environment variables from app.json are processed during the first deploy, before the predeploy script runs. The behavior depends on the variable configuration:
- Variables with
valueor simple string: The default value is set if the variable doesn't already exist - Variables with
generator: "secret": A random 64-character hex string is generated if the variable doesn't exist - Required variables without a value or generator: If a TTY is available, the user is prompted for a value. Otherwise, the deploy fails with an error
- Optional variables without a value: Skipped silently if no TTY is available
On subsequent deploys:
- Variables are NOT re-set unless
sync: trueis specified - Variables with
sync: trueare always set to their configured value, overwriting any manual changes - Variables that already have values are not modified
Examples
Simple default value:
{
"env": {
"WEB_CONCURRENCY": "5"
}
}
Generated secret (recommended for API keys, tokens, etc.):
{
"env": {
"SECRET_KEY_BASE": {
"description": "Base secret for session encryption",
"generator": "secret"
}
}
}
Required variable that must be provided:
{
"env": {
"DATABASE_URL": {
"description": "PostgreSQL connection URL",
"required": true
}
}
}
Variable that stays in sync with app.json:
{
"env": {
"FEATURE_FLAGS": {
"value": "new_ui,dark_mode",
"sync": true
}
}
}
Formation
{
"formation": {
"web": {
"max_parallel": 1,
"quantity": 1
}
}
}
(object, optional) A key-value object for process type configuration. Keys are the names of the process types. The values are an object containing one or more of the following properties:
autoscaling(map of string to object, optional) autoscaling rules. See the autoscaling section for more detailsmax_parallel: (int, optional) number of instances to deploy in parallel at a given timequantity: (int, optional) number of processes to maintain. Default 1 for web processes, 0 for all others.service: (map of string to oject, optional) governs how non-web processes are exposed as services on the network
Autoscaling
{
"formation": {
"web": {
"autoscaling": {
"cooldown_period_seconds": 300,
"max_quantity": 10,
"min_quantity": 1,
"polling_interval_seconds": 30,
"triggers": {
"http": {
"metadata": {
"url": "https://example.com/health"
}
}
}
}
}
}
}
(object, optional) A key-value object for autoscaling configuration. Keys are the names of the process types. The values are an object containing one or more of the following properties:
cooldown_period_seconds: (int, optional)max_quantity: (int, optional)min_quantity: (int, optional)polling_interval_seconds: (int, optional)triggers: (object, optional)
An autoscaling trigger consists of the following properties:
name: (string, optional)type: (string, optional)metadata: (object, optional)
Service
{
"formation": {
"internal-web": {
"service": {
"exposed": true
}
}
}
}
(object, optional) A key-value object specifying how to expose non-web processes as services.
service: (boolean, optional) Whether to expose a process as a network service. ThePORTvariable will be set to 5000.
Healthchecks
{
"healthchecks": {
"web": [
{
"type": "startup",
"name": "web check",
"description": "Checking if the app responds to the /health/ready endpoint",
"path": "/health/ready",
"attempts": 3
}
]
}
}
(object, optional) A key-value object specifying healthchecks to run for a given process type.
attempts: (int, optional)command: (list of strings, optional)content: (string, optional)httpHeaders: (list of header objects, optional)initialDelay: (int, optional)listening: (boolean, optional)name: (string, optional)path: (string, optional)port: (int, optional)scheme: (string, optional)timeout: (int, optional)type: (string, optional)uptime: (int, optional)wait: (int, optional)warn: (boolean, optional)onFailure: (object, optional)
Scripts
{
"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"
}
}
(object, optional) A key-value object specifying scripts or shell commands to execute at different stages in the build/release process.
dokku.predeploy: (string, optional)- 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
dokku.postdeploy: (string, optional)- 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
postdeploy: (string, optional)- 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