Single-runtime image

See all of the options for controlling your apps and how they’re built and deployed on Upsun Fixed.

For single-app projects, use the .platform.app.yaml file, which is typically located at the root of your Git repository, to configure the apps in your single-runtime image.

See a comprehensive example of a configuration in a .platform.app.yaml file.

Multi-app projects can be set up in various ways.

For reference, see a log of changes to app configuration.

Top-level properties

The following table lists all properties available at the top level of the YAML for the app.

The Set in instance column defines whether the given property can be overridden within a web or workers instance. To override any part of a property, you have to provide the entire property.

Root directory

Some of the properties you can define are relative to your app’s root directory. The root defaults to the location of your .platform.app.yaml file.

That is, if a custom value for source.root is not provided in your configuration, the default behavior is equivalent to the above.

To specify another directory, for example for a multi-app project, use the source.root property.

type

The type defines the base container image used to run the application. The version is the major (X) and sometimes minor (X.Y) version numbers, depending on the service, as in the following table. Security and other patches are taken care of for you automatically.

Available languages and their supported versions:

Example configuration

These are used in the format runtime:version:

type: 'php:8.5'

build

The only property of the build dictionary is flavor, which specifies a default set of build tasks to run. Flavors are language-specific.

See what the build flavor is for your language:

• Node.js
• PHP

In all languages, you can also specify a flavor of none to take no action at all (which is the default for any language other than PHP and Node.js).

build:
  flavor: none

dependencies

Installs global dependencies as part of the build process. They’re independent of your app’s dependencies and are available in the PATH during the build process and in the runtime environment. They’re installed before the build hook runs using a package manager for the language.

The format for package names and version constraints are defined by the specific package manager.

An example of dependencies in multiple languages:

applications:
  APP_NAME:
    type: 'nodejs:24'
    source:
      root: "/"
    dependencies:
      php: # Specify one Composer package per line.
        drush/drush: '8.0.0'
        composer/composer: '^2'
      python2: # Specify one Python 2 package per line.
        behave: '*'
        requests: '*'
      python3: # Specify one Python 3 package per line.
        numpy: '*'
      ruby: # Specify one Bundler package per line.
        sass: '3.4.7'
      nodejs: # Specify one NPM package per line.
        pm2: '^4.5.0'

runtime

The following table presents the various possible modifications to your PHP runtime:

You can also set your app’s runtime timezone.

Extensions

You can enable PHP extensions just with a list of extensions:

applications:
  APP_NAME:
    type: 'php:8.5'
    source:
      root: "/"
    runtime:
      extensions:
        - geoip
        - tidy

Alternatively, if you need to include configuration options, use a dictionary for that extension:

applications:
  APP_NAME:
    type: 'php:8.5'
    source:
      root: "/"
    runtime:
      extensions:
        - geoip
        - name: blackfire
          configuration:
            server_id: foo
            server_token: bar

In this case, the name property is required.

Sizing hints

The following table shows the properties that can be set in sizing_hints:

See more about PHP-FPM workers and sizing.

Combine single-runtime and composable images

In a multiple application context, you can use a mix of single-runtime images and composable images.

The following sample configuration includes two applications:

• frontend – uses a single-runtime image
• backend – uses a composable image
  In this app, PHP is the primary runtime and is started automatically (PHP-FPM also starts automatically when PHP is the primary runtime). For details, see the PHP as a primary runtime section in the Composable image topic.

applications:
  frontend:
    # this app uses the single-runtime image with a specific node.js runtime
    type: 'nodejs:24'
  backend:
    # this app uses the composable image and specifies two runtimes
    type: "composable:8.4"
    stack:
      runtimes:
        - "php@8.4":
            extensions:
              - apcu
              - sodium
              - xsl
              - pdo_sqlite
        - "python@3.13"
      packages:
        - "python313Packages.yq" # python package specific