> ## Documentation Index > Fetch the complete documentation index at: https://developer.upsun.com/llms.txt > Use this file to discover all available pages before exploring further. # Choose an image type > Configure your app and control how it's built and deployed on Upsun. An *image* represents the configuration of the container that contains the application (or service) that you want to deploy. Choosing the image type for the container that best suits your application is the first and most important decision in configuring how your application is deployed. Upsun offers two image types for applications — [single-runtime](/docs/configure-apps/app-reference/single-runtime-image) and [composable](/docs/configure-apps/app-reference/composable-image) — plus support for running [self-hosted services from public Docker images](/docs/add-services/docker-images). You define all of these options as `applications` in your `.upsun/config.yaml` file. ## Which image type should you choose? | **Criteria / Use‑case** | **Single‑runtime image** | **Composable image** | **Docker image** | | ----------------------------------------------------- | -------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------- | ------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------- | ------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------- | | **When it’s best used (typical use case)** | Good for simple applications that need only one runtime. | Best for applications needing custom secondary runtimes, static assets, or custom binaries/tools. | Best when you already build and ship container images outside Upsun and want to deploy them as is. | | **# of runtimes per container** | One — a single runtime per container. | Zero or more — you can define multiple runtimes (or none) per container. | Defined entirely by the image itself. | | **Packages permitted / how dependencies are managed** | Only the base runtime and its extensions are permitted directly. To add non-runtime packages, you must use build-phase installation via hooks or dependencies. See [Keys used](#keys-used-in-each-image-type) below. | Supports multiple runtimes, extensions, packages and services. You define everything in the `stack` key (runtimes + Nix packages). See [Keys used](#keys-used-in-each-image-type) below. | All dependencies are bundled inside the image. Upsun does not add or modify packages. | | **Manual configuration / setup burden** | Lower: using a supported runtime means less manual setup; adding downloads, dependencies, and packages might require use of build hooks, which might complicate configuration. | Higher: you manually define the composition of the container or `stack` (runtimes + packages) of Nix packages. More flexible but requires more setup. | Low on the Upsun side — see [Configure an app](/docs/add-services/docker-images#configure-an-app) in the "Self-hosted services from public Docker images" topic. Image preparation and maintenance happen in your own build pipeline. | | **Maintenance & updates (patches, upgrades)** | Upsun handles image updates (minor and patch updates; security patches) automatically on deployment | You need to redeploy often to apply Nix package updates; update cadence depends on package maintainers.
Your team must be comfortable with upgrading, testing, and refactoring images promptly when Nix a channel becomes deprecated (every six months). | **You are responsible for security patches.** Upsun does not patch public Docker image runtimes. You must rebuild and redeploy the image to apply updates. | | **Flexibility (versions, custom binaries, tools)** | Limited to supported runtimes + permitted extensions. If you require combinations not supported by Upsun, you may hit limits (e.g. certain PHP + Node.js/Python combos). | High — you can mix runtimes, pick specific package versions, and include custom binaries/tools via Nix. | Highest — full control over the image contents, runtime, and tooling. You can use any Docker image from a public registry. | | **When to reconsider / migrate** | If you need many packages (beyond runtime extensions), complex dependencies, multiple runtimes, or custom tools, consider migrating to composable. | If you don’t need the complexity (just a simple runtime and minimal packages), composable may be unnecessary overhead. | If patch responsibility or storage cost is a concern. Images must be under 4 GB; larger images require a [support ticket](/docs/get-started/here/support#create-a-support-ticket). Build hooks are not supported. | ## Keys used in each image type The single-runtime and composable image types share many configuration keys. Differences in syntax or meaning are noted as needed in [Image properties](/docs/configure-apps/image-properties). * Single-runtime image: Use the [`build`](/docs/configure-apps/app-reference/single-runtime-image#build), [`dependencies`](/docs/configure-apps/app-reference/single-runtime-image#dependencies), and [`runtime`](/docs/configure-apps/app-reference/single-runtime-image#runtime) keys * Composable image: Use the [`stack.runtimes` and `stack.packages`](/docs/configure-apps/app-reference/composable-image#stack) keys * Docker image (for deploying self-hosted services): Use the [`type`](/docs/add-services/docker-images/index#configure-an-app) key and the `image.name` key (see [Configure an app](/docs/add-services/docker-images/index#configure-an-app)). The `build`, `dependencies`, `runtime`, and `stack` keys do not apply. Build hooks are not supported. ## Multi-app projects In a multiple application context, you can use a mix of single-runtime images, composable images, and Docker images. See the examples in the [single-runtime image](/docs/configure-apps/app-reference/single-runtime-image#combine-single-runtime-and-composable-images) topic and [composable image](/docs/configure-apps/app-reference/composable-image#combine-single-runtime-and-composable-images) topic. For a sample Docker image app, see the [Docker image](/docs/add-services/docker-images) topic.