mirror of
https://github.com/dokku/dokku.git
synced 2026-05-18 05:05:46 +02:00
291 lines
8.7 KiB
Markdown
291 lines
8.7 KiB
Markdown
# 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.json` format used by Dokku is based on the one [supported by Heroku](https://devcenter.heroku.com/articles/app-json-schema), not all Heroku functionality is supported by Dokku.
|
||
|
||
## Buildpacks
|
||
|
||
```json
|
||
{
|
||
"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
|
||
|
||
```json
|
||
{
|
||
"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
|
||
|
||
```json
|
||
{
|
||
"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 purpose
|
||
- `value`: (string, optional) Default value for the variable
|
||
- `required`: (boolean, optional, default: `true`) Whether the variable must have a value
|
||
- `generator`: (string, optional) Function to generate the value. Currently only `"secret"` is supported, which generates a 64-character cryptographically secure hex string
|
||
- `sync`: (boolean, optional, default: `false`) If `true`, 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:
|
||
|
||
1. **Variables with `value` or simple string**: The default value is set if the variable doesn't already exist
|
||
2. **Variables with `generator: "secret"`**: A random 64-character hex string is generated if the variable doesn't exist
|
||
3. **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
|
||
4. **Optional variables without a value**: Skipped silently if no TTY is available
|
||
|
||
On subsequent deploys:
|
||
- Variables are NOT re-set unless `sync: true` is specified
|
||
- Variables with `sync: true` are always set to their configured value, overwriting any manual changes
|
||
- Variables that already have values are not modified
|
||
|
||
### Examples
|
||
|
||
**Simple default value:**
|
||
```json
|
||
{
|
||
"env": {
|
||
"WEB_CONCURRENCY": "5"
|
||
}
|
||
}
|
||
```
|
||
|
||
**Generated secret (recommended for API keys, tokens, etc.):**
|
||
```json
|
||
{
|
||
"env": {
|
||
"SECRET_KEY_BASE": {
|
||
"description": "Base secret for session encryption",
|
||
"generator": "secret"
|
||
}
|
||
}
|
||
}
|
||
```
|
||
|
||
**Required variable that must be provided:**
|
||
```json
|
||
{
|
||
"env": {
|
||
"DATABASE_URL": {
|
||
"description": "PostgreSQL connection URL",
|
||
"required": true
|
||
}
|
||
}
|
||
}
|
||
```
|
||
|
||
**Variable that stays in sync with app.json:**
|
||
```json
|
||
{
|
||
"env": {
|
||
"FEATURE_FLAGS": {
|
||
"value": "new_ui,dark_mode",
|
||
"sync": true
|
||
}
|
||
}
|
||
}
|
||
```
|
||
|
||
## Formation
|
||
|
||
```json
|
||
{
|
||
"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 details
|
||
- `max_parallel`: (int, optional) number of instances to deploy in parallel at a given time
|
||
- `quantity`: (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
|
||
|
||
```json
|
||
{
|
||
"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
|
||
|
||
```json
|
||
{
|
||
"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. The `PORT` variable will be set to 5000.
|
||
|
||
## Healthchecks
|
||
|
||
```json
|
||
{
|
||
"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
|
||
|
||
```json
|
||
{
|
||
"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
|