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.

applications:
  APP_NAME:
    type: "python:3.13"
    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        

applications:
  APP_NAME:
    type: "composable:25.05"
    source:
      root: "/"
    stack: 
      runtimes: [ "python3.13" ]
    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

applications:
  myapp:
    type: 'python:3.13'
    source:
      root: "/"
    web:
      upstream:
        socket_family: tcp
        protocol: http

applications:
  myapp:
    type: "composable:25.05"
    source:
      root: "/"
    stack: 
      runtimes: [ "[email protected]" ]
    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.

applications:
  myapp:
    type: 'python:3.13'
    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

applications:
  myapp:
    type: "composable:25.05"
    source:
      root: "/"
    stack: 
      runtimes: [ "[email protected]" ]
    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

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:

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

applications:
  myapp:
    type: "composable:25.05"
    source:
      root: "/"
    stack: 
      runtimes: [ "[email protected]" ]
    web:
      locations:
        '/':
          passthru: true
          request_buffering:
            enabled: true
            max_request_size: 250m