# Source: https://docs.upsun.com/create-apps/app-reference/composable-image.md

# 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](https://nix.dev), 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](https://search.nixos.org/packages).
- The packages you add are built in isolation, enabling you to install different versions of the same package.
- With [Nix](https://nix.dev/reference/glossary#term-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](https://docs.upsun.com../multi-app.md).

You can also skip directly to this [comprehensive example](https://docs.upsun.com/create-apps.md#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 {#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`](https://docs.upsun.com/create-apps/app-reference/composable-image.md#example-stack-configuration) 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.

**Note**: 

 - The ``type`` and ``stack`` properties are unique to the composable image type and are described later in this topic. All other properties are available in both single-runtime and composable images — click a property name to view its details in a separate topic.
 - The ``stack`` key replaces the ``build``, ``dependencies``, and ``runtime`` keys that are available in the [single-runtime image](https://docs.upsun.com/create-apps/app-reference/single-runtime-image.md).

| Name                 | Type                                                                                     | Required | Set in instance? | Description                                                                                                                                                                                                                                                      |
|----------------------|------------------------------------------------------------------------------------------|----------|------------------|------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------|
| [`type`](#type)             | A type                                                         | Yes      | No               | [Defines the version of the Nix channel](#supported-nix-channels). Mandatory in each application that uses the composable image. Example: `type: "composable:25.11"`.                                                                                                                                                                                      |
| [`stack`](#stack)              |  `runtimes` and/or  `packages` arrays                                                     | Yes      | No               | Specifies [Upsun-supported `runtimes`](#supported-nix-packages) and extra [Nixpkgs `packages`](https://search.nixos.org/packages) beyond those in the `type` channel.                                                                                            |
| [`container_profile`](https://docs.upsun.com/create-apps/image-properties/container_profile.md)  | A container profile |          | Yes              | Determines which combinations of CPU and RAM an app or service container can use. Default value is `HIGH_CPU`; see [Resources](#resources) if using multiple runtimes.                                                                                                                                                                                                                            |
| [`relationships`](https://docs.upsun.com/create-apps/image-properties/relationships.md)      | A dictionary of relationships                                          |          | Yes              | Connections to other services and apps.                                                                                                                                                                                                                          |
| [`mounts`](https://docs.upsun.com/create-apps/image-properties/mounts.md)             | A dictionary of mounts                                                        |          | Yes              | Directories that are writable even after the app is built. Allocated disk for mounts is defined with a separate resource configuration call using `upsun resources:set`.                                                                            |
|[`web`](https://docs.upsun.com/create-apps/image-properties/web.md)                | A web instance                                                                   |          | N/A              | How the web application is served.                                                                                                                                                                                                                               |
| [`workers`](https://docs.upsun.com/create-apps/image-properties/workers.md)            | A worker instance                                                            |          | N/A              | Alternate copies of the application to run as background processes.                                                                                                                                                                                              |
| `timezone`           | `string`                                                                                 |          | No               | The timezone for crons to run. Format: a [TZ database name](https://en.wikipedia.org/wiki/List_of_tz_database_time_zones). Defaults to `UTC`, which is the timezone used for all logs no matter the value here. See also [app runtime timezones](https://docs.upsun.com../timezone.md). |
| [`access`](https://docs.upsun.com/create-apps/image-properties/access.md)             | An access dictionary                                                          |          | Yes              | Access control for roles accessing app environments.                                                                                                                                                                                                             |
| [`variables`](https://docs.upsun.com/create-apps/image-properties/variables.md)          | A variables dictionary                                                     |          | Yes              | Variables to control the environment.                                                                                                                                                                                                                            |
| [`firewall`](https://docs.upsun.com/create-apps/image-properties/firewall.md)           | A firewall dictionary                                                       |          | Yes              | Outbound firewall rules for the application.                                                                                                                                                                                                                     |
| [`hooks`](https://docs.upsun.com/create-apps/image-properties/hooks.md)          | A hooks dictionary                                                                 |          | No               | Specifies commands and/or scripts to run in the `build`, `deploy`, and `post_deploy` phases.                                                                                                                                                                                           |
| [`crons`](https://docs.upsun.com/create-apps/image-properties/crons.md)              | A cron dictionary                                                              |          | No               | Scheduled tasks for the app.                                                                                                                                                                                                                                     |
| [`source`](https://docs.upsun.com/create-apps/image-properties/source.md)             | A source dictionary                                                           |          | No               | Details about the app’s source code and available operations.                                                                                                                                                                                       |
| [`additional_hosts`](https://docs.upsun.com/create-apps/image-properties/additional_hosts.md)   | An additional hosts dictionary                                      |          | Yes              | Mappings of hostnames to IP addresses.                                                                                                                                                                                                                                        |
| [`operations`](https://docs.upsun.com/create-apps/runtime-operations.md)         | A dictionary of runtime operations                 |          | No               | Runtime operations for the application.                                                                                                                                                                                                                          |

## `type` {#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.11` for `<APP_NAME>`, use the following syntax:

```yaml  {location=".upsun/config.yaml"}
applications:
  <APP_NAME>:
      type: "composable:25.11"
```

### Supported Nix channels

Upsun supports the following Nix channel versions:

- `25.11`

View the list of [supported Nix runtimes](#supported-nix-packages) in the `stack` section below.

## `stack` {#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](#example-stack-configuration) that follows this table.

| Name            | Type                | Required | Additional keys | Description                                                       |
|-----------------|---------------------|------------------| ----------|-------------------------------------------------------------------|
| `runtimes` | array     |  No        | `extensions`, `disabled_extensions`, and related subkeys | An array of 1+ language runtimes specified as `""` or ``.<BR>The first declared runtime (or _[primary runtime](#multiple-runtimes-primary-runtime)_) is started automatically.<BR>See the complete list of [supported runtimes](#supported-nix-packages) below. |
| `packages`      | array |  No        | `package`, `channel`, additional keys to demonstrate passthrough flexibility | Additional Nix tools/libraries, using the channel from `type` unless overridden locally by specifying the `package` and its `channel`. Format: ``   |

**Runtimes extensions or packages?**: 

Be sure you understand where to specify a runtime’s additional components. For example:

 - **PHP**: Manage extensions by using the ``stack.runtimes.extensions`` and ``stack.runtimes.disabled_extensions`` keys.

 - Note: In some scenarios, you might [add PHP settings](https://docs.upsun.com/languages/php.md#customize-php-settings) via environment variables or ``php.ini``.

 - **Python**: Install extra packages via the ``stack.packages`` key.

See the [example ](#example-stack-configuration) below.
For other runtimes, see the [Languages](https://docs.upsun.com/languages.md) section.

### Example: `stack` configuration {#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.14`
- **Nix packages:**
  - `yarn` and `python313Packages.yq` from the channel defined in `type`
  - `python313Packages.jupyterlab` (with config) and `wkhtmltopdf` from the `unstable` channel

```yaml  {location=".upsun/config.yaml"}
applications:
  <APP_NAME>:
    type: "composable:25.11"
    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.14"
      packages:
        - yarn                      # Package manager
        - python313Packages.yq      # Python package
        - package: python313Packages.jupyterlab
          channel: unstable
        - package: wkhtmltopdf      # Conversion tool
          channel: unstable
```

**Warning**: 

Although ``nix`` commands are available during the build phase, they are not supported at runtime because the final image is read-only.

When you use the Upsun composable image, you don’t need ``nix`` commands.
Anything you declare under the ``stack`` key is automatically installed and the binaries are included in your ``$PATH``, making them immediately available to use.
For example, to [start a secondary runtime](#multiple-runtimes-primary-runtime),
you can run it directly in your [start](https://docs.upsun.com/create-apps/image-properties/web.md#web-commands) without using ``nix run``.

### Working with multiple runtimes: primary runtime {#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](https://docs.upsun.com/create-apps/image-properties/web.md#web-commands).
To find out which start command to use, go to the [Languages](https://docs.upsun.com/languages.md) 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](#resources) section of this topic.

See the [`stack` configuration example](#example-stack-configuration) above, which declares multiple runtimes.

### PHP as a primary runtime {#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](#example-stack-configuration) 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](https://docs.upsun.com/languages/php.md#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](https://devcenter.upsun.com/posts/when-php-fpm-runs-out-of-workers-a-502-error-field-guide/) (Dev Center article)

### Upsun-supported Nix runtimes {#supported-nix-packages}

**Note**: 

Upsun officially supports the Nix runtimes listed below. To use them in your container, add them to the ``stack.runtimes`` array. 
Runtimes **not** listed below are supported only by Nix as Nixpkgs packages, not as Upsun runtimes. In those cases, add them to ``stack.packages``.  For example, if your app requires the [FrankenPHP](https://search.nixos.org/packages?channel=unstable&show=frankenphp&from=0&size=50&sort=relevance&type=packages&query=frankenphp) runtime from the ``unstable`` channel, you would add ``frankenphp`` to ``stack.packages``. See the [stack](#example-stack-configuration) above for a similar addition.

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.

| **Language**                                 | **Nix package** | **Supported version(s)**                        |
|----------------------------------------------|-----------------|-------------------------------------------------|
| [Clojure](https://clojure.org/)              | `clojure`       | 1                                               |
| [Elixir](https://docs.upsun.com/languages/elixir.md)             | `elixir`        | 1.191.181.17                          |
| [Go](https://docs.upsun.com/languages/go.md)                     | `golang`        | 1.251.24                                   |
| [Java](https://docs.upsun.com/languages/java.md)                 | `java`          | 25                                       |
| [Javascript/Bun](https://bun.sh/)            | `bun`           | 1                                               |
| [JavaScript/Node.js](https://docs.upsun.com/languages/nodejs.md) | `nodejs`        | 242220                         |
| [Perl](https://www.perl.org/)                | `perl`          | 5                                               |
| [PHP](https://docs.upsun.com/languages/php.md)                   | `php`           | 8.48.38.2                     |
| [Python](https://docs.upsun.com/languages/python.md)             | `python`        | 3.133.123.11 |
| [Ruby](https://docs.upsun.com/languages/ruby.md)                 | `ruby`          | 3.43.3                     |

### PHP extensions and Python packages {#php-extensions-and-python-packages}

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

1. Go to the [NixOS search](https://search.nixos.org/).
1. Enter a runtime and click **Search**.
1. 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.

![Screenshot of the Nix package sets selection for PHP@8.3](https://docs.upsun.com/images/nixos/nixos-packages.png "0.5")

  **Note: PHP extension names**: 

To help you find PHP extension names,
some maintainers provide a ``PHP upstream extension`` value in the [NixOS search engine](https://search.nixos.org/packages?channel=unstable&show=php82Extensions.gd).

      ![Screenshot of an upstream extension value shown in the NixOS search](https://docs.upsun.com/images/nixos/nixossearch-upstream-value.png)

If this information is not provided, copy the ``<EXTENSION-NAME>`` extension name from the appropriate ``<PHP><VERSION>Extensions.<EXTENSION-NAME>`` search result and add it to ``stack.runtimes.extensions`` as shown in the [stack](#example-stack-configuration) above.

4. Add extensions to `stack.runtimes.extensions` and packages to `stack.packages` as described in the [`stack`](#stack) section above.

## Resources (CPU, memory, disk space) {#resources}

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..stack.runtimes` key, you need to do one of the following:
- Change the [`.applications..container_profile`](https://docs.upsun.com/create-apps/image-properties/container_profile.md) to a profile that uses a larger container size.

- Change the [resource initialization policy](https://docs.upsun.com/manage-resources/resource-init.md) (the default CPU and RAM ratio) by running this command:

    ```bash
    upsun push --resources-init=manual
    ```

Related topics:
- For detailed steps for changing the container size, see the [Vertical scaling](https://docs.upsun.com/manage-resources/adjust-resources.md#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](https://docs.upsun.com/manage-resources/adjust-resources.md#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](https://docs.upsun.com/manage-resources.md) 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](https://docs.upsun.com/environments/backup.md).
- The downsize will fail if the disk contains more data than the target size.

## Combine single-runtime and composable images {#combine-single-runtime-and-composable-images}

In a [multiple application context](https://docs.upsun.com/create-apps/multi-app.md),
you can use a mix of [single-runtime images](https://docs.upsun.com/create-apps/app-reference/single-runtime-image.md)
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](#php-as-a-primary-runtime) section in this topic.

```yaml  {location=".upsun/config.yaml"}
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.11"
    stack:
      runtimes:
        - "php@8.4":
            extensions:
              - apcu
              - sodium
              - xsl
              - pdo_sqlite
        - "python@3.13"
      packages:
        - "python313Packages.yq" # python package specific
```