You control your application and the way it will be built and deployed on via a single configuration file,, located at the root of your application folder inside your Git repository.


The file is extremely flexible. Depending on your needs it could be less than 10 lines long or over 100. The only required keys are name, type, disk, and at least one “instance definition”, either a web or worker block. All others are optional.

Your application code can generate one or more application instances. Web instances can be accessed from the outside world, while workers cannot and just run a persistent background process. Otherwise they are very similar.

Different configuration properties can be applied to individual web and worker instances, or globally to all of them. In the most typical case, with one web instance and no workers, it’s common to just list each of the configuration directives below as a top-level property. However, they can also be specified within the web or worker blocks to apply to just those instances.

The following properties apply only at the global level, and cannot be replicated inside an instance definition.

  • name (required) - Sets the unique name of the application container.
  • type (required) - Sets the container base image to use, including application language.
  • timezone - Sets the timezone of cron tasks in application container.
  • build, dependencies, and hooks - Control how the application gets compiled. Note that this compilation happens before the application is copied into different instances, so any steps here will apply to all web and worker instances.
  • cron - Defines scheduled tasks for the application. Cron tasks will, technically, run as part of the web instance regardless of how many workers are defined.
  • source.root - This nested value specifies the path where all code for the application lives. It defaults to the directory where the file is defined. It is rarely needed except in advanced configurations.

The following properties can be set at the top level of the file and apply to all application instances, or set within a given instance definition and apply just to that one. If set in both places then the instance-specific one will take precedence, and completely replace the global one. That is, if you want to make a change to just one sub-property of one of the following keys you need to replicate the entire block.

  • size - Sets an explicit sizing hint for the application.
  • relationships - Defines connections to other services and applications.
  • access - Restricts SSH access with more granularity than the management console.
  • disk and mounts - Defines writable file directories for the application.
  • variables - Sets environment variables that control application behavior.
  • firewall - Defines outbound firewall rules for the application.

The file needs at least one of the following to define an instance, but may define both.

  • web - Controls how the web application is served.
  • worker - Defines alternate copies of the application to run as background processes.

Available resources 

Each web or worker instance is its own running container, which takes its own resources. The size key allows some control over how many resources each container gets and if omitted the system will select one of a few fixed sizes for each container automatically. All application and service containers are given resources out of a common pool defined by your plan size. That means the more containers you define, the fewer resources each one will get and you may need to increase your plan size.

Compression does not compress any dynamic responses generated by your application due to a well known security issue. While your application can compress its own response, doing so when the response includes any user-specific information, including a session cookie, opens up an attack vector over SSL/TLS connections. For that reason we recommend against compressing any generated responses.

Requests for static files that are served directly by are compressed automatically using either gzip or brotli compression if:

  • The request headers for the file support gzip or brotli.
  • The file is served directly from disk by, not passed through your application.
  • The file would be served with a cache expiration time in the future.
  • The file type is one of: html, javascript, json, pdf, postscript, svg, css, csv, plain text, or XML.

Additionally, if a file with a “.gz” or “.br” extension exists that will be served instead for the appropriate compression type regardless of the file type. That is, a request for styles.css that accepts a gzipped file (according to the request headers) will automatically return the contents of styles.css.gz if it exists. This approach supports any file type and offers some CPU optimization, especially if the cache lifetime is short.

Example configuration 

An example of a minimalist file for PHP, heavily commented, is below:


# The name of this application, which must be unique within a project.
name: 'app'

# The type key specifies the language and version for your application.
type: 'php:8.0'

# By default, composer 1 will be used. Specify composer 2 in the dependencies to get the latest version
        composer/composer: '^2'

# The relationships of the application with services or other applications.
# The left-hand side is the name of the relationship as it will be exposed
# to the application in the PLATFORM_RELATIONSHIPS variable. The right-hand
# side is in the form `<service name>:<endpoint name>`.
    database: 'mysqldb:mysql'

# The hooks that will be triggered when the package is deployed.
    # Build hooks can modify the application files on disk but not access any services like databases.
    build: |
                rm web/app_dev.php
    # Deploy hooks can access services but the file system is now read-only.
    deploy: |
                app/console --env=prod cache:clear

# The size of the persistent disk of the application (in MB).
disk: 2048

# The 'mounts' describe writable, persistent filesystem mounts in the application.
# The keys are directory paths relative to the application root. The values are a
# mount definition. In this case, `web-files` is just a unique name for the mount.
        source: local
        source_path: 'web-files'

# The configuration of the application when it is exposed to the web.
            # The public directory of the application relative to its root.
            root: 'web'
            # The front-controller script which determines where to send
            # non-static requests.
            passthru: '/app.php'
        # Allow uploaded files to be served, but do not run scripts.
        # Missing files get mapped to the front controller above.
            root: 'web/files'
            scripts: false
            allow: true
            passthru: '/app.php'

Upgrading from previous versions of the configuration file. 

Although we make an effort to always maintain backward compatibility in the format, we do from time to time upgrade the file and encourage you to upgrade as well.