Import a docker-compose stack

Publish a stack of public container images or builds from retained source from a Compose file using the portal or MCP. Review its services, ports, variables and persistent volumes, then choose the HTTP service that will receive your domain.

The importer supports image stacks and local builds from an account-owned retained upload. Review does not execute project code or fetch a repository. Use a current agent for deployment recovery; see agent updates. Local MCP support requires impreza-mcp 0.21.0+.

From the portal

Open My Apps → Advanced → Deploy a custom app and select Compose file.
Select a YAML file or paste its contents, up to 64 KiB. Use variable references for credentials instead of writing passwords directly in the file.
Click Review Compose to list services and declared TCP ports. Select the service that actually serves HTTP and enter its container Target port. Review again.
Read the changes, warnings and required variable names. Enter values under Environment variables, then choose the server, app name and domain.
Submit the deployment and follow its app card and deployment history. Review does not prove that an image can be downloaded or that the application will start.

Changing YAML, HTTP service or target port invalidates the review. The server repeats validation at creation. Imported services use the resource limits declared in their YAML; the image/Git CPU, memory and storage-path fields are disabled for this source.

Example: web and cache

services:
  web:
    image: nginx:alpine
    ports: ["8080:80"]
    cpus: "0.5"
    mem_limit: 128m
    depends_on: [cache]
    environment:
      APP_LABEL: "${APP_LABEL:-my-stack}"
  cache:
    image: redis:7-alpine
    cpus: "0.5"
    mem_limit: 128m
    volumes: [cache-data:/data]
volumes:
  cache-data: {}

Select web and target port 80. The cache is accessible to services sharing its private Docker network using the service name cache. This example demonstrates connectivity and storage; it does not configure an application to use Redis automatically. Pin image digests when you need a fixed image rather than a mutable tag.

From MCP

Call impreza_prepare_compose with compose_yaml. It requires read scope and returns configuration findings without creating resources.
Call it again with the selected web_service and integer target_port. Continue when the result is ready_for_review and the customer has reviewed the changes. blocked requires corrections; needs_input requires a service and port.
Call impreza_deploy_custom with mode: "compose", the same YAML/service/port, and compose_review_id set to the returned analysis_id. Also provide name, agent_id, runtime vars and the desired domain/onion settings. Creation requires deploy scope.

The prepare result includes services, volumes, variables, changes, warnings, errors and checks that remain unverified. Its parameters contains the reviewed selection for the creation call; retain the original YAML separately. The fingerprint covers YAML, service, port and the retained context identifier when supplied. It is not a stored executable plan, a reservation, or a promise about capacity, permissions or image access.

REST equivalents: POST /v1/platform/deployments/custom/compose/prepare and POST /v1/platform/deployments/custom. Supply compose_yaml as the only source at creation; do not combine it with image, git_url or manifest. An existing active name returns a conflict instead of creating a second stack; inspect the existing deployment before retrying. This is not a general idempotency-key API.

What the importer changes

Each container receives a deployment-specific name; declared named volumes receive stable, deployment-specific names. Existing external resources are not adopted.
Original host port bindings are removed from every service. Only the selected HTTP service gets a platform-managed loopback port and joins the shared reverse-proxy network. Other services keep their private networks; published database/UDP ports are not retained.
Services without an explicit restart policy receive unless-stopped. Initialization jobs referenced with service_completed_successfully instead default to "no" and must not restart. Select a serving HTTP service, not an initialization job. A service_healthy dependency needs an enabled health check in the file.
Top-level project name/version and extension metadata are not used for deployment. Review works with the resulting supported configuration.

Port hints describe the file, not a running listener. Select the actual HTTP port, even if the file has no port metadata. The application must listen on an interface reachable from its container network.

Variables and credentials

Use uppercase references such as ${DATABASE_PASSWORD}, ${DATABASE_PASSWORD:?Required} or ${CACHE_TTL:-120}. References without defaults require a supplied value; :? also rejects an empty value. Mapping/list environment syntax is supported. A pass-through entry such as - API_TOKEN becomes an explicit required variable rather than inheriting a value from the server.

vars supplies values for references; it is not injected into every service automatically. Declare the environment variables each container should receive. Variable values must be single-line strings, up to 4 KiB each, with no surrounding whitespace, quotes, backslashes, dollar signs or space followed by #. These restrictions prevent reinterpretation by the current agent's .env serialization. Up to 64 variables are supported. Platform and Docker control variable names are reserved. Use $$ in Compose commands when a dollar sign must reach the container unchanged.

Nested interpolation and alternative-value operators are not supported. Required variables and value restrictions are checked again during runtime-variable edits and redeploy. YAML and variable maps are redacted from request audit logs; nevertheless, keep literal credentials out of source files and image contents.

Retained source files

Retained source requires agent 0.6.11+ and local MCP 0.34.0+. Update older agents explicitly before deployment.

The importer accepts a retained context_id alongside the Compose YAML in review and deployment. Upload a gzip-compressed tar archive through the existing source-upload flow, then supply its identifier in the portal's Compose source field, REST request or impreza_prepare_compose/impreza_deploy_custom. Review and deploy must use the same YAML, HTTP service, port and context identifier. The upload must belong to the authenticated account.

Local build.context, dockerfile, literal target and explicit public args are supported. Paths stay inside this one upload; remote contexts, SSH forwarding, additional contexts and build-time secrets in imported Compose are rejected. Dockerfiles execute only when the deployment runs. Build arguments and copied source can enter image layers: do not put credentials there.

Services may reference env_file and declared file-backed configs/secrets. These are runtime files, distinct from build credentials. Environment files require explicit, single-line NAME=value assignments. Blank lines, comments and complete simple quotes are accepted; dollar interpolation, bare variable names, multiline values and escaped quoted values are rejected before queuing work. Use deployment variables in the reviewed Compose environment for parameterized values; the importer never authorizes reading the agent process environment. At most 100 source references and 1 MiB of combined auxiliary file contents are allowed. Paths cannot traverse parents or symlinks. Runtime files are stored under the archive hash so a later upload does not replace the files used by an earlier release. An agent must advertise compose-source-files-v1; an older agent is refused before dispatch and must be updated explicitly by its owner.

The agent preserves files referenced by the current configuration and retained releases, and reclaims unreferenced snapshots before staging another version. Corrupt or unreadable release records stop reclamation. A hard limit of 32 snapshots prevents unbounded growth. Manual rollback can select an earlier file version when the resource names, archive-relative filenames and mount destinations remain the same; changing storage or routing still requires an explicit redeploy. Rollback does not undo database writes. Requires agent 0.6.11+ for retained source files.

Supported configuration

A file can declare 1–12 services and up to 24 named volumes or networks. Use lowercase service/resource names starting with a letter, at most 63 characters. Supported service fields are image, container_name, command, entrypoint, environment, depends_on, expose, ports, volumes, networks, healthcheck, restart, user, working_dir, init, stop_grace_period, cpus, mem_limit and read_only.

Volumes must be declared local named volumes, mounted at absolute container paths; short syntax and simple long volume mounts with read_only are supported. Networks are deployment-private bridge networks; internal is supported, while service network assignments use a list of names. Port hints accept literal single TCP/UDP ports in short or long publication syntax, without ranges or variable expressions.

Host bind mounts, anonymous volumes, include, extends, external resources, custom drivers, profiles, host networking/privileges, static network addresses and aliases are unsupported. YAML aliases, custom tags, duplicate keys and excessive nesting are rejected. These findings must be corrected before this importer creates resources. Advanced custom manifests remain a separate flow.

Redeploy and recovery

The imported configuration is saved as a frozen custom manifest, so deployment reads report mode: "manifest". Redeploy reuses this source and the deployment's named volumes, with current runtime variable values. Choose a new deployment to change the imported service topology or image references; the importer does not edit an existing Compose source in place. An unpinned tag can still change when pulled again.

The existing agent preparation and recovery workflow applies. A failed image pull preserves running containers; an eligible previous release can recover after failed replacement. Data writes and migrations are not undone. A successful default startup is not continuous health monitoring or proof that every application endpoint works; the generated Node require_healthy_start option is not an import option. See deployment safety and rollback for the full behavior and limits.

The custom manifest security policy preserves the importer's deployment-scoped named volumes. Host bind mounts and host file inputs are refused before a deployment is queued.

Import a Compose stack