Single-runtime image

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

Use the .upsun/config.yaml file, located at the root of your Git repository, to configure the apps in a single-runtime image.

See a comprehensive example of a configuration in a .upsun/config.yaml file.

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

Primary application properties

In the .upsun/config.yaml file, configure each application as a unique key beneath the top-level applications key.

For example, if your deployed site requires a Javascript frontend application container and a Python backend application container, the .upsun/config.yaml file would start to look something like this:

applications:
  frontend:
    type: 'nodejs:24'
    # Additional frontend configuration
  backend:
    type: 'python:3.13'
    # Additional backend configuration

The following table presents all of the properties available to each unique app beneath the applications key.

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 root of the repository.

applications:
  frontend:
    type: 'nodejs:24'
    # Default behavior of source.root
    source:
      root: "/"

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:

applications:
  APP_NAME:
    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).

applications:
  myapp:
    source:
      root: "/"
    type: 'nodejs:24'
    build:
      flavor: none

dependencies

Installs global dependencies as part of the build process. They’re independent of the code dependencies of your application 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

This applies to PHP only.

The following table lists 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: SERVER_ID:
            server_token: SERVER_TOKEN:

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.

Resources (CPU, memory, and disk space)

By default, Upsun assigns a container profile and container size to each application and service on the first deployment of a project.

The container profile defines and enforces a specific CPU-to-memory ratio. The default container profile for an app or service in a composable image is HIGH_CPU.

Use the Upsun CLI or Console to manually adjust the allocated container size (CPU and memory resources)—that is, to perform a vertical‑scaling action. When you redeploy, the container runs with the CPU‑to‑memory ratio defined by its profile, so it enforces the size you specified.

Related topics:

• For detailed steps for changing the container size, see the Vertical scaling section of the “Resource configuration topic.
• For details about container sizes for each resource allocation strategy (shared CPU, guaranteed CPU, and initial allocation), see the Advanced: Container profiles section of the “Resource configuration” topic.
• To learn more about general resource management in Upsun, see the topics in the Manage resources section.

Downsize a disk

You can reduce the target disk size of an app. Keep in mind:

• Backups created before the downsize are incompatible and cannot be used; you must create new backups.
• The downsize will fail if the disk contains more data than the target size.

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:25.05"
    stack:
      runtimes:
        - "php@8.4":
            extensions:
              - apcu
              - sodium
              - xsl
              - pdo_sqlite
        - "python@3.13"
      packages:
        - "python313Packages.yq" # python package specific