Composable image

The Upsun composable image provides enhanced flexibility when defining your app. It enables you to install several runtimes and tools in your application container, in a “one image to rule them all” approach.

The composable image is built on Nix, which offers the following benefits:

• You can add as many packages to your application container as you need, choosing from over 120,000 packages from the Nixpkgs collection.
• The packages you add are built in isolation, enabling you to install different versions of the same package.
• With Nix, there are no undeclared dependencies in your source code. What works on your local machine is guaranteed to work on any other machine.

This page introduces all the settings available to configure your composable image from your .upsun/config.yaml file (usually located at the root of your Git repository).
Note that multi-app projects can be set in various ways.

You can also skip directly to this comprehensive example of a composable image configuration in the “Configure apps” topic. This example includes all of the primary application properties listed in the table in the next section.

Primary application properties

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

In a composable image, you can add multiple runtimes to a single application container by defining them in the .applications.<APP_NAME>.stack key, described later in this topic.

The following table presents all of the properties available to each unique application.

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 must provide the entire property.

type

Required for all applications that use the composable image. Defines the version of the Nix channel that application uses.

For example, to specify the Nix channel 25.05 for APP_NAME, use the following syntax:

applications:
  APP_NAME:
      type: "composable:25.05"

Supported Nix channels

Upsun supports the following Nix channel versions:

• 25.05

View the list of supported Nix runtimes in the stack section below.

stack

You must define the stack element by using distinct runtimes and packages keys, as described in the following table.

See the example stack configuration that follows this table.

Example: stack configuration

The config.yaml file excerpt below shows the following stack configuration:

• Primary runtime: php@8.4 with additional extensions and one disabled extension
• Secondary runtimes: nodejs@24 and python@3.13
• Nix packages:
  • yarn and python313Packages.yq from the channel defined in type
  • python313Packages.jupyterlab (with config) and wkhtmltopdf from the unstable channel

applications:
  APP_NAME:
    type: "composable:25.05"
    stack:
      runtimes:
        - "php@8.4":
            extensions:
              - apcu
              - pdo_sqlite
              - facedetect
              - sodium
              - xsl
              - name: blackfire   # php@8.4 extension
                configuration:    # extension subkeys
                    server_id: SERVER_ID
                    server_token: SERVER_TOKEN
            disabled_extensions:
              - gd
        - "nodejs@24"
        - "python@3.13"
      packages:
        - yarn                      # Package manager
        - python313Packages.yq      # Python package
        - package: python313Packages.jupyterlab
          channel: unstable
        - package: wkhtmltopdf      # Conversion tool
          channel: unstable

Working with multiple runtimes: primary runtime

If you add multiple runtimes to your application container, the first declared runtime becomes the primary runtime. The primary runtime is the one that is automatically started.

To start other declared runtimes (or secondary runtimes), you need to start them manually by using web commands. To find out which start command to use, go to the Languages section and visit the documentation page dedicated to your runtime.

Containers that define multiple runtimes typically require some resource sizing adjustments. For details, see the Resources section of this topic.

See the stack configuration example above, which declares multiple runtimes.

PHP as a primary runtime

If a PHP runtime is the first declared (or primary) runtime in the app:

• The PHP-FPM service starts automatically.

• You can configure the PHP-FPMP service by using request_terminate_timeout and sizing_hints keys in the app’s stack.runtimes key.

  The stack configuration example above declares PHP as a primary runtime but does not show these additional keys.

For the complete list of PHP extension keys and PHP-FPM sizing hints, see Modify your PHP runtime when using the composable image section in the “PHP” topic.

Related resource: When php-fpm runs out of workers: a 502 error field guide (Dev Center article)

Upsun-supported Nix runtimes

For some runtimes (such as Clojure), you can specify only a major version.
For other runtimes (such as Elixir), you can specify a major or a major.minor version. Security and other patches are applied automatically.

PHP extensions and Python packages

To discover which PHP extensions and Python packages are available for these runtimes:

1. Go to the NixOS search.
2. Enter a runtime and click Search.
3. In the Package sets side bar, select the right set of extensions/packages for your runtime version.
   You can choose the desired extensions/packages from the filtered results.

4. Add extensions to stack.runtimes.extensions and packages to stack.packages as described in the stack section above.

Resources (CPU, memory, 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.

If you define multiple runtimes in an application’s .applications.<app_name>.stack.runtimes key, you need to do one of the following:

• Change the .applications.<app_name>.container_profile to a profile that uses a larger container size.
  

• Change the resource initialization policy (the default CPU and RAM ratio) by running this command:

  upsun push --resources-init=manual

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 this 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