Docker Compose

Use Compose when several containers belong together or you already have a Compose definition. Upvale translates supported services into managed applications and, when explicitly selected, native databases. You keep the normal resource pages, runtime visibility, and deployment history.

This is a managed deployment workflow. Upvale validates the file and shows how it will run on your cluster before applying it.

Deploy a first Compose service

1. Create a project and assign its environment to a working cluster.
2. Open the project and choose Compose, or choose Add Service → Compose stack and select the project and environment.
3. Select Example, paste YAML, or use Import Compose to upload a .yaml or .yml file.
4. Select Save draft, then Preview changes.
5. Review any errors and the service and network preview.
6. Configure platform overrides where needed, then save and preview again.
7. Select Deploy. Upvale opens Deployments so you can follow the result.

For a minimal web service:

services:
  web:
    image: nginx:alpine
    expose:
      - "80"

This creates an application on the Compose environment's default network. expose does not make it public. After the first preview, expand Platform overrides → web, add a Public route, and set its target port to 80. Configure DNS and TLS as described in Application routes, then save, preview, and deploy.

Saving a draft changes no running containers. Deploy uses the reviewed saved draft; edits made afterward require another preview.

Permissions

Editing and previewing Compose requires Manage workloads and Manage secrets. Deploying also requires Manage deployments. Changing a Compose definition that manages native databases requires Manage databases. Using external managed networks also requires Manage infrastructure.

Source and input files can contain credentials, so access to the editor requires secrets permission. Users with monitoring access can inspect the safe deployment summary without receiving the source values.

Compose editor

Compose source

Keep one complete Compose document in the editor. Import Compose replaces the editor's source; Example inserts the starter file when the editor is empty. Each saved draft gets a version.

Publish your images to a registry first. Upvale resolves image tags to digests during preview so the plan identifies the image being deployed.

Variables

Use Add variable to supply values for expressions such as ${APP_TAG} or ${DATABASE_PASSWORD} in YAML. Enter a name and value; keep Sensitive checked for passwords, tokens, and private configuration.

services:
  api:
    image: ghcr.io/example/api:${APP_TAG}
    environment:
      DATABASE_PASSWORD: ${DATABASE_PASSWORD}

Replace the example image with your own. Set APP_TAG as a non-sensitive variable because it is part of the public image identifier. Keep DATABASE_PASSWORD sensitive.

Sensitive interpolation is allowed in environment values, commands, entrypoints, health-check tests, and config contents. It is rejected in public fields such as image names or working directories. Missing required variables produce an error rather than silently taking values from the machine running Upvale.

An explicitly uploaded .env file supplies interpolation defaults. Values in Variables take precedence. Values from .env are treated as sensitive unless explicitly replaced with a non-sensitive variable.

Input files

Use Add file or Upload for files referenced by env_file or configs. The path must match the Compose reference, for example config/app.conf. Uploads initially use the file's name; edit its path if your YAML expects a subdirectory.

Upvale reads only the files supplied in this section. A path in YAML does not read a file from your computer or from a cluster node. Use relative paths inside the bundle; absolute paths and parent-directory traversal are rejected.

Platform overrides

After preview, expand a service under Platform overrides:

Save and preview after changing overrides. A stale preview cannot be deployed.

The Advanced JSON editor exposes the same overrides plus resource limits and service renames. CPU limits use cpus (1 is one vCore), and memory limits use memoryMb. For example:

{
  "services": {
    "web": {
      "limits": { "cpus": 0.5, "memoryMb": 256 }
    }
  },
  "renames": {
    "old_service": "new_service"
  }
}

Use renames when changing a service key in YAML and retaining the existing managed resource. Without this mapping, the preview treats the old key as removed and the new key as a new service. Confirm the intended identity and retained volume in the preview before deploying.

Read a deployment preview

Each service is marked create, update, unchanged, or remove. Expand it to see:

• Its resource type, image digest, and changed fields.
• Network aliases and service dependencies.
• Published ports.
• Persistent volumes and assigned storage nodes.
• The effective, protected configuration summary.

An interruption badge means deployment needs to interrupt that service. Pay particular attention to removals and persistent storage.

Network topology shows each logical YAML network, its member services, the actual managed network, and whether ingress is attached. Errors prevent deployment. Warnings identify a consequence you should review; informational messages explain transformations such as a scoped network name.

Plans expire. If the draft, relevant configuration, or deployment state changes, create a fresh preview rather than reusing the old plan.

Networks and service discovery

Compose preserves declared network membership. A service connected to frontend and backend joins both; a service connected only to backend does not automatically join frontend.

When YAML omits explicit networks, Compose's default network becomes an environment-scoped managed overlay network. Non-external network names are scoped to the environment to avoid collisions between projects. Service names and declared aliases remain usable inside their attached networks.

services:
  web:
    image: nginx:alpine
    networks: [frontend]
  api:
    image: ghcr.io/example/api:v1
    networks: [frontend, backend]
  cache:
    image: redis:7
    networks: [backend]
networks:
  frontend: {}
  backend: {}

The example API can address cache on backend. The web service has no direct membership in backend. Replace the API image with one you control before deploying.

Use no explicit driver or driver: overlay. An explicit bridge or custom network driver is rejected. Upvale does not silently flatten multiple networks into one. For a routed service, choose the network Traefik should join under Ingress network.

For a shared existing network, declare it external: true and supply its authorized managed network ID in Platform overrides. A literal Docker network name alone is not a binding. This is how an appropriate existing network can be shared with other managed resources.

These are container networks. Whether the cluster nodes communicate over a private VPC, public addresses, or managed WireGuard is a separate choice described in Networking.

Ports, dependencies, and runtime settings

A public HTTP route and a published port are different. HTTP routes use Traefik and can provide TLS and request middleware. Published ports expose the container protocol directly through Swarm. Use a route for ordinary websites; publish database ports only when that is the access method you intend.

Persistent volumes

A named volume belongs to one Compose service. Select its Storage node before deployment. Services with writable local volumes require exactly one replica.

A volume is local to its node. Changing the node is not a data migration, so moving existing persistent placement is rejected. Shared volumes between services, host bind mounts, external volumes, and custom volume drivers are not supported by Compose import.

Removing a Compose service keeps its data volume. Reintroducing the same service name later does not automatically reattach the retained data; preview warns that it starts with empty storage. Plan a restore or migration if you need that data. See Storage and backups.

Convert a supported database

A database-looking image stays an application unless you select Managed database. This conversion is for supported single-node native databases; it does not turn arbitrary YAML into an HA database.

The current adapter supports official PostgreSQL images with numeric major versions 14–18, and official Redis images with numeric major versions 6–8. It requires one replica, one writable named data volume at the image's data directory, and an online storage node.

For PostgreSQL, use the normal image command and only POSTGRES_USER, POSTGRES_PASSWORD, and POSTGRES_DB environment settings. Set an explicit password of 16–256 characters, preferably through a sensitive variable or secret binding. For Redis, use redis-server --requirepass with an explicit password; --appendonly yes or --appendonly no is also supported. Redis does not configure its password from environment variables.

The adapter uses public official images; remove any registry-credentials override. It rejects custom entrypoints, user/working-directory overrides, read-only root filesystems, and explicit init settings. PostgreSQL accepts an optional pg_isready -U <user> -d <database> health check; remove other custom health checks. Preview reports the exact setting to change. An optional database port mapping must be one host-mode TCP mapping for the engine's port. HTTP routes are not supported for the database adapter.

Choose the resource type before the service's first deployment. An existing Compose application cannot be changed into a native database in place. Changes to an existing database's engine, major version, database name, username, volume identity, or storage node need a separate migration. Use the native Database creation flow for managed PostgreSQL HA, standbys, and read replicas. MongoDB and scheduled jobs are not Compose conversion targets.

Update, retry, or restore a deployment

To update services, edit the source, variables, files, or overrides, then Save draft → Preview changes → Deploy. The preview shows only the changes it plans to apply.

Open Deployments to see all Compose revisions. Select a revision for per-service results and operation steps. Operation opens the detailed progress and error page.

If a deployment fails because of a temporary runtime problem, resolve it and use Retry deployment on the failed revision. Retry uses that revision's captured configuration. If the YAML, image, variables, or overrides need changing, save a new draft, preview it, and deploy a new revision instead. A deployment can have completed some services before another failed; inspect each service's result rather than assuming the whole revision was applied or rolled back.

Use Compare revisions, select From and To, and select Compare to inspect configuration changes. Restore as draft copies an earlier revision into the editor, replacing the current draft. It does not change running services until you preview and deploy it, and does not restore database data.

Remove Compose services

Remove a service from YAML, save, and preview to remove that one managed service. To remove all Compose-managed services, use Compose management → Remove managed resources → Review removal, review the list, then select Remove resources.

This stops and removes the Compose services, keeps their data volumes, and disables Compose management for the environment. Manually created resources are kept. Saving a new draft can enable Compose again after removal has completed.

Current import limits

Compose supports up to 50 services, 32 used networks, 32 input files, and 256 variables. Source is limited to 256 KiB; the complete input bundle is limited to 1 MiB.

Unsupported settings fail validation rather than being silently ignored. These include local image builds, profiles, multiple Compose documents, include, extends, privileged container options, custom or isolated network settings, host bind mounts, shared or external volumes, file-mounted Compose secrets, and dependencies that require a job to complete. Use the dedicated scheduled job form for cron work.

Use the native application form when you need one of its advanced controls that Compose import does not support. Configuration stored under x- extension keys is retained as metadata and has no deployment effect.