Composable image

The Upsun Fixed composable image provides enhanced flexibility when defining your app. It allows 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 total isolation, so you can 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 .platform.app.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 on the “Configure apps” page. This example includes all of the top-level properties listed in the table in the next section.

Top-level properties

All application configuration takes place in a .platform.app.yaml file, with each application configured under a unique key beneath the top-level applications key.

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

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: [email protected] with additional extensions and one disabled extension
• Secondary runtimes: nodejs@24 and [email protected]
• 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:
        - "[email protected]":
            extensions: 
              - apcu
              - pdo_sqlite
              - facedetect
              - sodium
              - xsl
              - name: blackfire   # [email protected] extension
                configuration:    # extension subkeys
                    server_id: SERVER_ID
                    server_token: SERVER_TOKEN
            disabled_extensions:
              - gd
        - "nodejs@24"
        - "[email protected]"
      packages:
        - yarn                      # Package manager
        - python313Packages.yq      # Python package 
        - package: python313Packages.jupyterlab   # Python package with optional Nix configuration
          channel: unstable
          configuration:
            withMathjax: false      # Disable MathJax support
            withMimeExtensions: true
        - 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 Fixed 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.

To change the container size, which is a vertical‑scaling action, you must change your plan size. 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 must change your plan size to Medium (M) or larger.

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:8.4" 
    stack:
      runtimes:
        - "[email protected]":
            extensions:
              - apcu
              - sodium
              - xsl
              - pdo_sqlite
        - "[email protected]"
      packages:
        - "python313Packages.yq" # python package specific