web

A web instance that defines how the web application is served.

Optional in single-runtime and composable images.

Use the web key to configure the web server running in front of your app.

For single-runtime images, default values might vary based on the image type, which defines the base container used to run the application.

See some examples of how to configure what’s served.

commands (web commands)

pre_start command

The pre_start command is not blocking, which means the deploy hook may start running before the pre_start command finishes. This can lead to unexpected behavior if pre_start performs setup tasks that deploy depends on.
To avoid issues, make sure any critical initialization in pre_start can complete quickly or is safe to run concurrently with deploy.

start command

On all containers other than PHP, it’s a best practice to include a start command. This command runs every time your app is restarted, regardless of whether new code is deployed.

On PHP containers, start is optional and defaults to starting PHP-FPM (/usr/bin/start-php-app). You can set it explicitly on a PHP container to run a dedicated process, such as React PHP or Amp. See Alternate start commands in the PHP topic.

post_start command

You can use the post_start command to ensure your app is fully active before traffic is routed to it. This command can perform checks or wait until your application starts listening on the expected port.

For example, if your framework needs several seconds to initialize (for example, to build caches or establish database connections), post_start can help coordinate the handover to ensure that the app receives traffic only after it is initialized.

Example:

This example contains two web commands:

• A start command that starts the application every time, whether or not new code is deployed.
• A post_start command that repeatedly checks whether a service on localhost is responding.

name: APP_NAME
type: "python:3.14"
source:
  root: "/"
web:
  commands:
    start: 'uwsgi --ini conf/server.ini'
    post_start: |
      date
      curl -sS --retry 20 --retry-delay 1 --retry-connrefused localhost -o /dev/null      

APP_NAME:
  type: "composable:26.05"
  source:
    root: "/"
  stack: 
    runtimes: [ "python3.14" ]
  web:
    commands:
      start: 'uwsgi --ini conf/server.ini'
      post_start: |
        date
        curl -sS --retry 20 --retry-delay 1 --retry-connrefused localhost -o /dev/null        

upstream

name: myapp
type: 'python:3.14'
source:
  root: "/"
web:
  upstream:
    socket_family: tcp
    protocol: http

myapp:
  type: "composable:26.05"
  source:
    root: "/"
  stack: 
    runtimes: [ "python@3.14" ]
  web:
    upstream:
      socket_family: tcp
      protocol: http

Where to listen

Where to listen depends on your setting for web.upstream.socket_family (defaults to tcp).

If your application isn’t listening at the same place that the runtime is sending requests, you see 502 Bad Gateway errors when you try to connect to your website.

locations

Each key in the locations dictionary is a path on your site with a leading /. For example.com, a / matches example.com/ and /admin matches example.com/admin. When multiple keys match an incoming request, the most-specific applies.

The following table presents possible properties for each location:

Rules

The rules dictionary can override most other keys according to a regular expression. The key of each item is a regular expression to match paths exactly. If an incoming request matches the rule, it’s handled by the properties under the rule, overriding any conflicting rules from the rest of the locations dictionary.

Under rules, you can set all the other possible locations properties except root, index, rules and request_buffering.

In the following example, the allow key disallows requests for static files anywhere in the site. This is overridden by a rule that explicitly allows common image file formats.

name: myapp
type: 'python:3.14'
source:
  root: "/"
web:
  locations:
    '/':
      # Handle dynamic requests
      root: 'public'
      passthru: '/index.php'
      # Disallow static files
      allow: false
      rules:
        # Allow common image files only.
        '\.(jpe?g|png|gif|svgz?|css|js|map|ico|bmp|eot|woff2?|otf|ttf)$':
          allow: true

myapp:
  type: "composable:26.05"
  source:
    root: "/"
  stack: 
    runtimes: [ "python@3.14" ]
  web:
    locations:
      '/':
        # Handle dynamic requests
        root: 'public'
        passthru: '/index.php'
        # Disallow static files
        allow: false
        rules:
          # Allow common image files only.
          '\.(jpe?g|png|gif|svgz?|css|js|map|ico|bmp|eot|woff2?|otf|ttf)$':
            allow: true

Dynamic response compression

Static files are compressed automatically, but responses generated by your app aren’t. Set dynamic_compression to true on a location to compress them:

name: myapp
type: 'php:8.5'  
source:
  root: "/"   
web:
  locations:
    '/':
      root: 'public'
      passthru: '/index.php'
      dynamic_compression: true

myapp:  
  type: "composable:26.05"  
  source:
    root: "/"
  stack:
    runtimes: [ "php@8.5" ]
  web:
    locations:
      '/':
        root: 'public'
        passthru: '/index.php'
        dynamic_compression: true

The algorithm is chosen based on the request’s Accept-Encoding header, with Brotli preferred and gzip as the fallback. Requests without that header get an uncompressed response. Compressed responses carry a Vary: Accept-Encoding header. Responses that already have a Content-Encoding header are left alone, so an app that compresses its own output isn’t compressed twice.

Compression starts at 256 bytes, on a best-effort basis: the web server can only check the size of responses that declare a Content-Length, which means chunked responses are compressed whatever their size.

To keep some paths uncompressed, turn the setting on for the location and off in a rule:

name: myapp
type: 'php:8.5'
source:
  root: "/"
web:
  locations:
    '/':
      root: 'public'
      passthru: '/index.php'
      dynamic_compression: true
      rules:
        # Leave the authenticated area uncompressed.
        '^/account/':
          dynamic_compression: false

myapp:
  type: "composable:26.05"
  source:
    root: "/"
  stack:
    runtimes: [ "php@8.5" ]
  web:
    locations:
      '/':
        root: 'public'
        passthru: '/index.php'
        dynamic_compression: true
        rules:
          # Leave the authenticated area uncompressed.
          '^/account/':
            dynamic_compression: false

Enable compression on the location and opt out per rule, not the other way around. A rule that turns compression on inside a location where it’s off doesn’t survive the passthru rewrite, which leaves the traffic uncompressed on a typical PHP app. A rule that turns compression off applies to both direct hits and requests served through passthru.

Apps serving large volumes of public, cacheable HTML from the origin get the most out of the setting, especially behind a content delivery network (CDN) that can’t compress what the origin sends it.

Request buffering

Request buffering is enabled by default to handle chunked requests as most app servers don’t support them. The following table shows the keys in the request_buffering dictionary:

The default configuration would look like this:

name:  myapp
type: 'python:3.14'
source:
  root: "/"
web:
  locations:
    '/':
      passthru: true
      request_buffering:
        enabled: true
        max_request_size: 250m

myapp:
  type: "composable:26.05"
  source:
    root: "/"
  stack: 
    runtimes: [ "python@3.14" ]
  web:
    locations:
      '/':
        passthru: true
        request_buffering:
          enabled: true
          max_request_size: 250m