Reference for App Specification

Validated on 6 October 2020 • Posted on 6 October 2020

As an alternative to configuring your app in the control panel, you can define an app specification using YAML. YAML-based app specs are useful for deploying fully-configured apps with the DigitalOcean API or using doctl, the DigitalOcean command-line tool.

YAML File Structure

This is a clickable list of the annotations in the YAML file, presented in the nested hierarchy that the YAML file uses.

name

String. The name of the app. Must be unique across all apps in the same account.

Minimum length: 2. Maximum length: 32.

Must comply with the following regular expression: ^[a-z][a-z0-9-]{0,30}[a-z0-9]$
services (array)

Array of Objects. Workloads which expose publicy-accessible HTTP services.
- name
  
  String. The name. Must be unique across all components within the same app.
  
  Minimum length: 2. Maximum length: 32.
  
  Must comply with the following regular expression: ^[a-z][a-z0-9-]{0,30}[a-z0-9]$
- git
  
  Object. A Git repo to use as component’s source. Only one of git, github, gitlab, or image must be set.
  - repo_clone_url
    
    String. The clone URL of the repo. Example: https://github.com/digitalocean/sample-golang.git
  - branch
    
    String. The name of the branch to use
- github
  
  Object. A GitHub repo to use as component’s source. Only one of git, github, gitlab, or image must be set.
  - repo
    
    String. The name of the repo in the format owner/repo. Example: digitalocean/sample-golang
    
    Must comply with the following regular expression: ^[^/]+/[^/]+$
  - branch
    
    String. The name of the branch to use
  - deploy_on_push
    
    Boolean. Whether to automatically deploy new commits made to the repo
- image
  
  Object. An image to use as the component’s source. Only one of git, github, gitlab, or image must be set.
  - registry_type
    String. The registry type.
    
    DOCR: The DigitalOcean container registry type.
    
    DOCKER_HUB: The DockerHub container registry type.
  - registry
    
    String. The registry name. Must be left empty for the DOCR registry type. Required for the DOCKER_HUB registry type.
  - repository
    
    String. The repository name.
  - tag
    
    String. The repository tag. Defaults to latest if not provided.
- gitlab
  
  Object. A GitLab repo to use as component’s source. Only one of git, github, gitlab, or image must be set.
  - repo
    
    String. The name of the repo in the format owner/repo or owner/subgroup/repo. Example: digitalocean/sample-golang or digitalocean/subgroup/sample-golang
    
    Must comply with the following regular expression: ^[^/]+(/[^/]+)+$
  - branch
    
    String. The name of the branch to use
  - deploy_on_push
    
    Boolean. Whether to automatically deploy new commits made to the repo
- dockerfile_path
  
  String. The path to the Dockerfile relative to the root of the repo. If set, it will be used to build this component. Otherwise, App Platform will attempt to build it using buildpacks.
- build_command
  
  String. An optional build command to run while building this component from source.
- run_command
  
  String. An optional run command to override the component’s default.
- source_dir
  
  String. An optional path to the working directory to use for the build. For Dockerfile builds, this will be used as the build context. Must be relative to the root of the repo.
- environment_slug
  
  String. An environment slug describing the type of this app. For a full list, please refer to the product documentation.
- envs (array)
  
  Array of Objects. A list of environment variables made available to the component.
  - key
    
    String. The name
    
    Must comply with the following regular expression: ^[_A-Za-z][_A-Za-z0-9]*$
  - value
    
    String. The value. If the type is SECRET, the value will be encrypted on first submission. On following submissions, the encrypted value should be used.
  - scope
    String. The visibility scope
    
    RUN_TIME: Made available only at run-time
    
    BUILD_TIME: Made available only at build-time
    
    RUN_AND_BUILD_TIME: Made available at both build and run-time
  - type
    String. The type
    
    GENERAL: A plain-text environment variable
    
    SECRET: A secret encrypted environment variable
- instance_size_slug
  
  String. The instance size to use for this component. Default: basic-xxs
- instance_count
  
  Integer. The amount of instances that this component should be scaled to. Default: 1
- http_port
  
  Integer. The internal port on which this service’s run command will listen. Default: 8080 If there is not an environment variable with the name PORT, one will be automatically added with its value set to the value of this field.
- routes (array)
  
  Array of Objects. A list of HTTP routes that should be routed to this component.
  - path
    
    String. An HTTP path prefix. Paths must start with / and must be unique across all components within an app.
- health_check
  
  Object. A health check to determine the availability of this component.
  - initial_delay_seconds
    
    Integer. The number of seconds to wait before beginning health checks.
  - period_seconds
    
    Integer. The number of seconds to wait between health checks.
  - timeout_seconds
    
    Integer. The number of seconds after which the check times out.
  - success_threshold
    
    Integer. The number of successful health checks before considered healthy.
  - failure_threshold
    
    Integer. The number of failed health checks before considered unhealthy.
  - http_path
    
    String. The route path used for the HTTP health check ping. If not set, the HTTP health check will be disabled and a TCP health check used instead.
- cors
  
  Object. A Cross-Origin Resource Sharing policy (CORS).
  - allow_origins (array)
    
    Array of Objects. The set of allowed CORS origins. This configures the Access-Control-Allow-Origin header.
    - exact
      
      String. Exact string match. Only 1 of exact, prefix, or regex must be set.
      
      Minimum length: 1. Maximum length: 256
    - prefix
      
      String. Prefix-based match. Only 1 of exact, prefix, or regex must be set.
      
      Minimum length: 1. Maximum length: 256
    - regex
      
      String. RE2 style regex-based match. Only 1 of exact, prefix, or regex must be set. For more information about RE2 syntax, see: https://github.com/google/re2/wiki/Syntax
      
      Minimum length: 1. Maximum length: 256
  - allow_methods (array)
    
    Array of Strings. The set of allowed HTTP methods. This configures the Access-Control-Allow-Methods header.
  - allow_headers (array)
    
    Array of Strings. The set of allowed HTTP request headers. This configures the Access-Control-Allow-Headers header.
  - expose_headers (array)
    
    Array of Strings. The set of HTTP response headers that browsers are allowed to access. This configures the Access-Control-Expose-Headers header.
  - max_age
    
    String. An optional duration specifiying how long browsers can cache the results of a preflight request. This configures the Access-Control-Max-Age header. Example: 5h30m.
  - allow_credentials
    
    Boolean. Whether browsers should expose the response to the client-side JavaScript code when the request’s credentials mode is include. This configures the Access-Control-Allow-Credentials header.
- internal_ports (array)
  
  Array of Int64s. The ports on which this service will listen for internal traffic.
static_sites (array)

Array of Objects. Content which can be rendered to static web assets.
- name
  
  String. The name. Must be unique across all components within the same app.
  
  Minimum length: 2. Maximum length: 32.
  
  Must comply with the following regular expression: ^[a-z][a-z0-9-]{0,30}[a-z0-9]$
- git
  
  Object. A Git repo to use as component’s source. Only one of git, github, or gitlab must be set.
  - repo_clone_url
    
    String. The clone URL of the repo. Example: https://github.com/digitalocean/sample-golang.git
  - branch
    
    String. The name of the branch to use
- github
  
  Object. A GitHub repo to use as component’s source. Only one of git, github, or gitlab must be set.
  - repo
    
    String. The name of the repo in the format owner/repo. Example: digitalocean/sample-golang
    
    Must comply with the following regular expression: ^[^/]+/[^/]+$
  - branch
    
    String. The name of the branch to use
  - deploy_on_push
    
    Boolean. Whether to automatically deploy new commits made to the repo
- gitlab
  
  Object. A GitLab repo to use as component’s source. Only one of git, github, or gitlab must be set.
  - repo
    
    String. The name of the repo in the format owner/repo or owner/subgroup/repo. Example: digitalocean/sample-golang or digitalocean/subgroup/sample-golang
    
    Must comply with the following regular expression: ^[^/]+(/[^/]+)+$
  - branch
    
    String. The name of the branch to use
  - deploy_on_push
    
    Boolean. Whether to automatically deploy new commits made to the repo
- dockerfile_path
  
  String. The path to the Dockerfile relative to the root of the repo. If set, it will be used to build this component. Otherwise, App Platform will attempt to build it using buildpacks.
- build_command
  
  String. An optional build command to run while building this component from source.
- source_dir
  
  String. An optional path to the working directory to use for the build. For Dockerfile builds, this will be used as the build context. Must be relative to the root of the repo.
- environment_slug
  
  String. An environment slug describing the type of this app. For a full list, please refer to the product documentation.
- output_dir
  
  String. An optional path to where the built assets will be located, relative to the build context. If not set, App Platform will automatically scan for these directory names: _static, dist, public, build.
- index_document
  
  String. The name of the index document to use when serving this static site. Default: index.html
- error_document
  
  String. The name of the error document to use when serving this static site. Default: 404.html. If no such file exists within the built assets, App Platform will supply one.
- envs (array)
  
  Array of Objects. A list of environment variables made available to the component.
  - key
    
    String. The name
    
    Must comply with the following regular expression: ^[_A-Za-z][_A-Za-z0-9]*$
  - value
    
    String. The value. If the type is SECRET, the value will be encrypted on first submission. On following submissions, the encrypted value should be used.
  - scope
    String. The visibility scope
    
    RUN_TIME: Made available only at run-time
    
    BUILD_TIME: Made available only at build-time
    
    RUN_AND_BUILD_TIME: Made available at both build and run-time
  - type
    String. The type
    
    GENERAL: A plain-text environment variable
    
    SECRET: A secret encrypted environment variable
- routes (array)
  
  Array of Objects. A list of HTTP routes that should be routed to this component.
  - path
    
    String. An HTTP path prefix. Paths must start with / and must be unique across all components within an app.
- cors
  
  Object. A Cross-Origin Resource Sharing policy (CORS).
  - allow_origins (array)
    
    Array of Objects. The set of allowed CORS origins. This configures the Access-Control-Allow-Origin header.
    - exact
      
      String. Exact string match. Only 1 of exact, prefix, or regex must be set.
      
      Minimum length: 1. Maximum length: 256
    - prefix
      
      String. Prefix-based match. Only 1 of exact, prefix, or regex must be set.
      
      Minimum length: 1. Maximum length: 256
    - regex
      
      String. RE2 style regex-based match. Only 1 of exact, prefix, or regex must be set. For more information about RE2 syntax, see: https://github.com/google/re2/wiki/Syntax
      
      Minimum length: 1. Maximum length: 256
  - allow_methods (array)
    
    Array of Strings. The set of allowed HTTP methods. This configures the Access-Control-Allow-Methods header.
  - allow_headers (array)
    
    Array of Strings. The set of allowed HTTP request headers. This configures the Access-Control-Allow-Headers header.
  - expose_headers (array)
    
    Array of Strings. The set of HTTP response headers that browsers are allowed to access. This configures the Access-Control-Expose-Headers header.
  - max_age
    
    String. An optional duration specifiying how long browsers can cache the results of a preflight request. This configures the Access-Control-Max-Age header. Example: 5h30m.
  - allow_credentials
    
    Boolean. Whether browsers should expose the response to the client-side JavaScript code when the request’s credentials mode is include. This configures the Access-Control-Allow-Credentials header.
- catchall_document
  
  String. The name of the document to use as the fallback for any requests to documents that are not found when serving this static site. Only 1 of catchall_document or error_document can be set.
workers (array)

Array of Objects. Workloads which do not expose publicly-accessible HTTP services.
- name
  
  String. The name. Must be unique across all components within the same app.
  
  Minimum length: 2. Maximum length: 32.
  
  Must comply with the following regular expression: ^[a-z][a-z0-9-]{0,30}[a-z0-9]$
- git
  
  Object. A Git repo to use as component’s source. Only one of git, github, gitlab, or image must be set.
  - repo_clone_url
    
    String. The clone URL of the repo. Example: https://github.com/digitalocean/sample-golang.git
  - branch
    
    String. The name of the branch to use
- github
  
  Object. A GitHub repo to use as component’s source. Only one of git, github, gitlab, or image must be set.
  - repo
    
    String. The name of the repo in the format owner/repo. Example: digitalocean/sample-golang
    
    Must comply with the following regular expression: ^[^/]+/[^/]+$
  - branch
    
    String. The name of the branch to use
  - deploy_on_push
    
    Boolean. Whether to automatically deploy new commits made to the repo
- image
  
  Object. An image to use as the component’s source. Only one of git, github, gitlab, or image must be set.
  - registry_type
    String. The registry type.
    
    DOCR: The DigitalOcean container registry type.
    
    DOCKER_HUB: The DockerHub container registry type.
  - registry
    
    String. The registry name. Must be left empty for the DOCR registry type. Required for the DOCKER_HUB registry type.
  - repository
    
    String. The repository name.
  - tag
    
    String. The repository tag. Defaults to latest if not provided.
- gitlab
  
  Object. A GitLab repo to use as component’s source. Only one of git, github, gitlab, or image must be set.
  - repo
    
    String. The name of the repo in the format owner/repo or owner/subgroup/repo. Example: digitalocean/sample-golang or digitalocean/subgroup/sample-golang
    
    Must comply with the following regular expression: ^[^/]+(/[^/]+)+$
  - branch
    
    String. The name of the branch to use
  - deploy_on_push
    
    Boolean. Whether to automatically deploy new commits made to the repo
- dockerfile_path
  
  String. The path to the Dockerfile relative to the root of the repo. If set, it will be used to build this component. Otherwise, App Platform will attempt to build it using buildpacks.
- build_command
  
  String. An optional build command to run while building this component from source.
- run_command
  
  String. An optional run command to override the component’s default.
- source_dir
  
  String. An optional path to the working directory to use for the build. For Dockerfile builds, this will be used as the build context. Must be relative to the root of the repo.
- environment_slug
  
  String. An environment slug describing the type of this app. For a full list, please refer to the product documentation.
- envs (array)
  
  Array of Objects. A list of environment variables made available to the component.
  - key
    
    String. The name
    
    Must comply with the following regular expression: ^[_A-Za-z][_A-Za-z0-9]*$
  - value
    
    String. The value. If the type is SECRET, the value will be encrypted on first submission. On following submissions, the encrypted value should be used.
  - scope
    String. The visibility scope
    
    RUN_TIME: Made available only at run-time
    
    BUILD_TIME: Made available only at build-time
    
    RUN_AND_BUILD_TIME: Made available at both build and run-time
  - type
    String. The type
    
    GENERAL: A plain-text environment variable
    
    SECRET: A secret encrypted environment variable
- instance_size_slug
  
  String. The instance size to use for this component.
- instance_count
  
  Integer. The amount of instances that this component should be scaled to. Default: 1
jobs (array)

Array of Objects. Pre and post deployment workloads which do not expose publicly-accessible HTTP routes.
- name
  
  String. The name. Must be unique across all components within the same app.
  
  Minimum length: 2. Maximum length: 32.
  
  Must comply with the following regular expression: ^[a-z][a-z0-9-]{0,30}[a-z0-9]$
- git
  
  Object. A Git repo to use as component’s source. Only one of git, github, gitlab, or image must be set.
  - repo_clone_url
    
    String. The clone URL of the repo. Example: https://github.com/digitalocean/sample-golang.git
  - branch
    
    String. The name of the branch to use
- github
  
  Object. A GitHub repo to use as component’s source. Only one of git, github, gitlab, or image must be set.
  - repo
    
    String. The name of the repo in the format owner/repo. Example: digitalocean/sample-golang
    
    Must comply with the following regular expression: ^[^/]+/[^/]+$
  - branch
    
    String. The name of the branch to use
  - deploy_on_push
    
    Boolean. Whether to automatically deploy new commits made to the repo
- image
  
  Object. An image to use as the component’s source. Only one of git, github, gitlab, or image must be set.
  - registry_type
    String. The registry type.
    
    DOCR: The DigitalOcean container registry type.
    
    DOCKER_HUB: The DockerHub container registry type.
  - registry
    
    String. The registry name. Must be left empty for the DOCR registry type. Required for the DOCKER_HUB registry type.
  - repository
    
    String. The repository name.
  - tag
    
    String. The repository tag. Defaults to latest if not provided.
- gitlab
  
  Object. A GitLab repo to use as component’s source. Only one of git, github, gitlab, or image must be set.
  - repo
    
    String. The name of the repo in the format owner/repo or owner/subgroup/repo. Example: digitalocean/sample-golang or digitalocean/subgroup/sample-golang
    
    Must comply with the following regular expression: ^[^/]+(/[^/]+)+$
  - branch
    
    String. The name of the branch to use
  - deploy_on_push
    
    Boolean. Whether to automatically deploy new commits made to the repo
- dockerfile_path
  
  String. The path to the Dockerfile relative to the root of the repo. If set, it will be used to build this component. Otherwise, App Platform will attempt to build it using buildpacks.
- build_command
  
  String. An optional build command to run while building this component from source.
- run_command
  
  String. An optional run command to override the component’s default.
- source_dir
  
  String. An optional path to the working directory to use for the build. For Dockerfile builds, this will be used as the build context. Must be relative to the root of the repo.
- environment_slug
  
  String. An environment slug describing the type of this app. For a full list, please refer to the product documentation.
- envs (array)
  
  Array of Objects. A list of environment variables made available to the component.
  - key
    
    String. The name
    
    Must comply with the following regular expression: ^[_A-Za-z][_A-Za-z0-9]*$
  - value
    
    String. The value. If the type is SECRET, the value will be encrypted on first submission. On following submissions, the encrypted value should be used.
  - scope
    String. The visibility scope
    
    RUN_TIME: Made available only at run-time
    
    BUILD_TIME: Made available only at build-time
    
    RUN_AND_BUILD_TIME: Made available at both build and run-time
  - type
    String. The type
    
    GENERAL: A plain-text environment variable
    
    SECRET: A secret encrypted environment variable
- instance_size_slug
  
  String. The instance size to use for this component.
- instance_count
  
  Integer. The amount of instances that this component should be scaled to. Default: 1
- kind
  String. The type of job and when it will be run during the deployment process.
  - UNSPECIFIED: Default job type, will auto-complete to POST_DEPLOY kind.
  - PRE_DEPLOY: Indicates a job that runs before an app deployment.
  - POST_DEPLOY: Indicates a job that runs after an app deployment.
  - FAILED_DEPLOY: Indicates a job that runs after a component fails to deploy.
databases (array)

Array of Objects. Database instances which can provide persistence to workloads within the application.
- name
  
  String. The name. Must be unique across all components within the same app.
  
  Minimum length: 2. Maximum length: 32.
  
  Must comply with the following regular expression: ^[a-z][a-z0-9-]{0,30}[a-z0-9]$
- engine
  String. The database engine to use
  - MYSQL: MySQL
  - PG: PostgreSQL
  - REDIS: Redis
- version
  
  String. The version of the database engine
- production
  
  Boolean. Whether this is a production or dev database.
- cluster_name
  
  String. The name of the underlying DigitalOcean DBaaS cluster. This is required for production databases. For dev databases, if cluster_name is not set, a new cluster will be provisioned.
- db_name
  
  String. The name of the MySQL or PostgreSQL database to configure.
- db_user
  
  String. The name of the MySQL or PostgreSQL user to configure.
domains (array)

Array of Objects. A set of hostnames where the application will be available.
- domain
  
  String. The hostname for the domain
  
  Minimum length: 4. Maximum length: 253.
  
  Must comply with the following regular expression: ^((xn--)?[a-zA-Z0-9]+(-[a-zA-Z0-9]+)*\.)+[a-zA-Z]{2,}\.?$
- type
  String. The domain type, which can be one of the following:
  - DEFAULT: The default .ondigitalocean.app domain assigned to this app
  - PRIMARY: The primary domain for this app that is displayed as the default in the control panel, used in bindable environment variables, and any other places that reference an app’s live URL. Only one domain may be set as primary.
  - ALIAS: A non-primary domain
- wildcard
  
  Boolean. Indicates whether the domain includes all sub-domains, in addition to the given domain
- zone
  
  String. Optional. If the domain uses DigitalOcean DNS and you would like App Platform to automatically manage it for you, set this to the name of the domain on your account.
  
  For example, If the domain you are adding is app.domain.com, the zone could be domain.com.
region

String. The slug form of the geographical origin of the app. Reference our list of available datacenters and their respective slugs. Default: nearest available
envs (array)

Array of Objects. A list of environment variables made available to all components in the app.
- key
  
  String. The name
  
  Must comply with the following regular expression: ^[_A-Za-z][_A-Za-z0-9]*$
- value
  
  String. The value. If the type is SECRET, the value will be encrypted on first submission. On following submissions, the encrypted value should be used.
- scope
  String. The visibility scope
  - RUN_TIME: Made available only at run-time
  - BUILD_TIME: Made available only at build-time
  - RUN_AND_BUILD_TIME: Made available at both build and run-time
- type
  String. The type
  - GENERAL: A plain-text environment variable
  - SECRET: A secret encrypted environment variable