From 8f3f6c49f178149c4481394cf015f5c7fc6f9235 Mon Sep 17 00:00:00 2001 From: Jose Diaz-Gonzalez Date: Sat, 7 Dec 2024 14:46:52 -0500 Subject: [PATCH] docs: add documentation for all file formats dokku uses Some files - those maintained by external organizations - have a very light treatment and solely point to the upstream documentation to reduce any issues creating examples/documentation for them that may differ in the future. Closes #7315 --- docs/appendices/file-formats/app-json.md | 153 ++++++++++++++++++ .../file-formats/buildpacks-file.md | 14 ++ docs/appendices/file-formats/dockerfile.md | 3 + docs/appendices/file-formats/lambda-yml.md | 16 ++ .../file-formats/nginx-conf-sigil.md | 3 + docs/appendices/file-formats/nixpacks-toml.md | 3 + docs/appendices/file-formats/procfile.md | 48 ++++++ docs/appendices/file-formats/project-toml.md | 3 + docs/deployment/zero-downtime-deploys.md | 14 +- 9 files changed, 250 insertions(+), 7 deletions(-) create mode 100644 docs/appendices/file-formats/app-json.md create mode 100644 docs/appendices/file-formats/buildpacks-file.md create mode 100644 docs/appendices/file-formats/dockerfile.md create mode 100644 docs/appendices/file-formats/lambda-yml.md create mode 100644 docs/appendices/file-formats/nginx-conf-sigil.md create mode 100644 docs/appendices/file-formats/nixpacks-toml.md create mode 100644 docs/appendices/file-formats/procfile.md create mode 100644 docs/appendices/file-formats/project-toml.md diff --git a/docs/appendices/file-formats/app-json.md b/docs/appendices/file-formats/app-json.md new file mode 100644 index 000000000..1254d09f1 --- /dev/null +++ b/docs/appendices/file-formats/app-json.md @@ -0,0 +1,153 @@ +# 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. + +## Cron + +```json +{ + "crons": [ + { + "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) +- `schedule`: (string, required) + +## 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. + +### 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) + +## 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 diff --git a/docs/appendices/file-formats/buildpacks-file.md b/docs/appendices/file-formats/buildpacks-file.md new file mode 100644 index 000000000..ac2b38548 --- /dev/null +++ b/docs/appendices/file-formats/buildpacks-file.md @@ -0,0 +1,14 @@ +# .buildpacks + +The `.buildpacks` file is used to specify the buildpacks for an application. It is a list of buildpack URLs. + +```shell +https://github.com/heroku/heroku-buildpack-nodejs.git +https://github.com/heroku/heroku-buildpack-ruby.git +``` + +When installed, a buildpack is checked to see if it is a git repository via `git ls-remote`. If it is not, the buildpack is checked to see if it ends in `.tgz`, `.tar.gz`, `.tbz`, `tar.bz`, or `.tar` and is downloaded/extracted before being executed. + +If the buildpack is located on Github, a shorthand can be used in the form of `organization/buildpack-name`. This will be expanded to the `https://github.com/organization/heroku-buildpack-buildpack-name.git`. The `heroku-community` organization name is treated as `heroku`. + +Comments are not allowed in the `.buildpacks` file. diff --git a/docs/appendices/file-formats/dockerfile.md b/docs/appendices/file-formats/dockerfile.md new file mode 100644 index 000000000..59b21ccde --- /dev/null +++ b/docs/appendices/file-formats/dockerfile.md @@ -0,0 +1,3 @@ +# Dockerfile + +A Dockerfile is used to build a Docker image for an application. Please refer to the [Dockerfile reference](https://docs.docker.com/reference/dockerfile/) for more information. diff --git a/docs/appendices/file-formats/lambda-yml.md b/docs/appendices/file-formats/lambda-yml.md new file mode 100644 index 000000000..f390fe09f --- /dev/null +++ b/docs/appendices/file-formats/lambda-yml.md @@ -0,0 +1,16 @@ +# lambda.yml + +The `lambda.yml` file is used to configure a Lambda application. + +```yaml +--- +build_image: mlupin/docker-lambda:dotnetcore3.1-build +builder: dotnet +run_image: mlupin/docker-lambda:dotnetcore3.1 +``` + +## Fields + +`build_image`: A docker image that is accessible by the docker daemon. The `build_image` should be based on an existing Lambda image - builders may fail if they cannot run within the specified `build_image`. The build will fail if the image is inaccessible by the docker daemon. +`builder`: The name of a builder. This may be used if multiple builders match and a specific builder is desired. If an invalid builder is specified, the build will fail. +`run_image`: A docker image that is accessible by the docker daemon. The `run_image` should be based on an existing Lambda image - built images may fail to start if they are not compatible with the produced artifact. The generation of the `run_image` will fail if the image is inaccessible by the docker daemon. diff --git a/docs/appendices/file-formats/nginx-conf-sigil.md b/docs/appendices/file-formats/nginx-conf-sigil.md new file mode 100644 index 000000000..8f97fa58f --- /dev/null +++ b/docs/appendices/file-formats/nginx-conf-sigil.md @@ -0,0 +1,3 @@ +# nginx.conf.sigil + +The `nginx.conf.sigil` file is used to configure the nginx server for an application. The default template can be found [here](https://github.com/dokku/dokku/blob/master/plugins/nginx-vhosts/templates/nginx.conf.sigil). Dokku uses a tool named [sigil](https://github.com/gliderlabs/sigil) to generate the nginx configuration based on the template provided. diff --git a/docs/appendices/file-formats/nixpacks-toml.md b/docs/appendices/file-formats/nixpacks-toml.md new file mode 100644 index 000000000..3d1baff00 --- /dev/null +++ b/docs/appendices/file-formats/nixpacks-toml.md @@ -0,0 +1,3 @@ +# nixpacks.toml + +The `nixpacks.toml` file is used to configure an application when built with the `nixpacks` builder. Please refer to the [nixpacks.toml documentation](https://nixpacks.com/docs/configuration/file.md) for more information. diff --git a/docs/appendices/file-formats/procfile.md b/docs/appendices/file-formats/procfile.md new file mode 100644 index 000000000..270988f58 --- /dev/null +++ b/docs/appendices/file-formats/procfile.md @@ -0,0 +1,48 @@ +# Procfile + +A Procfile is a file that was [promoted by Heroku](https://blog.heroku.com/the_new_heroku_1_process_model_procfile) for their platform as an easy way to specify one or more distinct processes to run within Heroku. This format has since been picked up by various other tools and platforms. + +## General Overview + +The `procfile-util` tool expects a Procfile to be defined as one or more lines containing one of: + +- a comment (preceeded by a `#` symbol or two `//` characters) +- a process-type/command combination (with optional trailing whitespace or trailing comment) + - when there is a trailing comment, the `#` symbol/`//` characters _must_ be preceeded by one or more `whitespace` characters. +- a blank line (with optional trailing whitespace) + +Comments and blank lines are ignored, while process-type/command combinations look like the following: + +``` +: +``` + +The syntax is defined as follows: + +- `` – any character in the class `[A-Za-z0-9_-]+`, a process type is a name for your command, such as `web`, `worker`, `urgentworker`, `clock`, etc. +- `` – a command used to launch the process, such as `rake jobs:work` + +Additional rules are as follows: + +- contain at most 63 characters + +A Procfile that does not match any of the above rules will be considered invalid, and not be processed. This is to avoid issues where a Procfile may contain merge conflicts or other improper content, thus resulting in unwanted runtime behavior for applications. + +Finally, process types within a Procfile may not overlap and must be unique. Rather than assuming that the last or first specified is correct, `procfile-util` will fail to parse the Procfile with the relevant error. + +### Strict Mode + +> Strict mode can be triggered on `procfile-util` via the `--strict` flag. + +In strict mode, the character set of a process type changes. + +- `` – a valid DNS Label Name as per [RFC 1123](https://tools.ietf.org/html/rfc1123), a process type is a name for your command, such as `web`, `worker`, `urgentworker`, `clock`, etc. + +This syntax differs common interpretations of valid `` values in that we define the process type as a DNS Label name, versus the regex `[A-Za-z0-9_]+`. The reason for this is that processes defined within Procfiles are commonly used in DNS entries. Rather than have a second level of platform-specific validation in place, this project implicitly defines the format for the process-type. + +Given the above, a valid process type can be generalized to the following rules (as taken from the [Kubernetes documentation](https://kubernetes.io/docs/concepts/overview/working-with-objects/names/#dns-label-names)): + +- contain at most 63 characters +- contain only lowercase alphanumeric characters or '-' +- start with an alphanumeric character +- end with an alphanumeric character diff --git a/docs/appendices/file-formats/project-toml.md b/docs/appendices/file-formats/project-toml.md new file mode 100644 index 000000000..f5411a75c --- /dev/null +++ b/docs/appendices/file-formats/project-toml.md @@ -0,0 +1,3 @@ +# project.toml + +The project descriptor file allows app developers to provide configuration for apps deployed to Dokku via the `pack` builder. Please refer to the [project.toml documentation](https://buildpacks.io/docs/reference/config/project-descriptor/) for more information. diff --git a/docs/deployment/zero-downtime-deploys.md b/docs/deployment/zero-downtime-deploys.md index 68b8cece8..b811b2d1e 100644 --- a/docs/deployment/zero-downtime-deploys.md +++ b/docs/deployment/zero-downtime-deploys.md @@ -150,13 +150,13 @@ One or more healthchecks can be defined in the `app.json` file - see the [deploy { "healthchecks": { "web": [ - { - "type": "startup", - "name": "web check", - "description": "Checking if the app responds to the /health/ready endpoint", - "path": "/health/ready", - "attempts": 3 - } + { + "type": "startup", + "name": "web check", + "description": "Checking if the app responds to the /health/ready endpoint", + "path": "/health/ready", + "attempts": 3 + } ] } }