Docker overview
Gateway gives Docker workloads a durable product identity rather than treating a running container as the whole application. That identity holds configuration, access grants, lifecycle history, relationships, and the desired state that Gateway can reconcile after an interruption.
Choose the highest-level lifecycle that matches the application:
- Container: one directly managed runtime with a focused configuration and lifecycle.
- Deployment: a stable application identity with two runtime slots for health-gated blue/green releases and rollback.
- Compose Project: a discovered external application or a Gateway-managed single-node application with validated configuration, immutable revisions, lifecycle operations, logs, Routes, and database bindings.
- Git source: a delivery input for Containers, Deployments, and Pages. It is not a separate application entity.
Workload Availability (HA) is available on Business and Enterprise for eligible mount-free Containers, Deployments, and whole Compose Projects. It adds fixed-count replication or single-serving failover across independent Docker nodes to the existing resource identity.
Choose the operating model
Section titled “Choose the operating model”The decision is primarily about ownership and recovery, not the number of fields in a form.
| Need | Recommended model | Main tradeoff |
|---|---|---|
| One service with a simple lifecycle | Container | Direct and flexible, but releases and rollback are operator-managed |
| Health-gated releases with a retained rollback candidate | Deployment | Stronger release safety, with two managed runtime slots |
| Several services that must change as one application | Compose Project | One revision and operation boundary, one node per placement; optional whole-project Availability on Business/Enterprise |
| Reproducible artifacts from source control | Git source plus an owning resource | Adds build provenance; deployment safety still comes from Container, Deployment, Compose, or Pages |
Choose the highest-level owner that represents how the application should be changed during a normal release and recovered during an incident. Do not model a multi-service application as unrelated Containers merely to avoid Compose, and do not choose Deployment when the application has shared writable state that cannot safely exist across release slots.
The platform lead should define who owns the application resource, its data, its public Routes, its registry access, and its rollback decision. Gateway records and enforces those boundaries, but it cannot decide whether an application-level data migration is reversible.
Ownership boundaries
Section titled “Ownership boundaries”Gateway owns the metadata and desired state for resources it creates or adopts. The target Docker daemon owns the runtime process, image cache, local storage implementation, and network attachment. A managed resource can therefore be unavailable while its desired state remains recorded; recovery starts by restoring daemon or node connectivity, then allowing Gateway to reconcile.
Some Docker objects belong to a higher-level owner. Deployment slots are controlled through their Deployment, and Compose-labelled containers are grouped under their discovered project context. Do not mutate owner-managed children through a standalone lifecycle path: direct changes can create drift between the running daemon state and Gateway’s recorded configuration.
Gateway-managed internal resources may include labels, runtime names, networks, volumes, credentials, build artifacts, and task records. Treat these as implementation details unless an action in Gateway explicitly exposes them. Deleting or renaming them through Docker tooling can break reconciliation, routing, or a future rollback.
How lifecycle work is performed
Section titled “How lifecycle work is performed”Long-running changes are represented as Tasks or operations. An operation records intent, progresses through daemon work, and finishes with a success or failure result that can be inspected later. Starting a second conflicting action while one is active can be rejected or deferred; wait for the current operation before retrying.
Before changing a workload, review its dependent Routes, database bindings, grants, mounted volumes, source settings, and restart policy. Before deleting it, decide whether its data and public entry points must be retained elsewhere. A successful runtime stop is not the same as a completed deletion.
Safe operational sequence
Section titled “Safe operational sequence”- Confirm the selected Docker node is online and has the required runtime capability.
- Inspect the resource owner and related resources before editing configuration.
- Make one intentional lifecycle change and follow its Task to completion.
- Verify health, application logs, and the expected route or private connection.
- Keep a known-good image or prior Deployment slot until the recovery window has passed.
If an operation fails, use its diagnostics to distinguish image, configuration, storage, port, permission, and node-connectivity failures. Correct the identified prerequisite and retry from Gateway. Do not remove Gateway-owned Docker objects as a generic recovery step.
Success criteria
Section titled “Success criteria”A workload is ready when its desired and observed state agree, the owning operation completed, health and logs are acceptable, and the real access path works. For public applications that means the Route; for private applications it may be a Secure Link or database dependency. A running process without verified access is not a successful deployment.
For every production workload, retain a known-good artifact, document persistent data and recovery ownership, and define the rollback window. Test the recovery action before an incident. Operator-level resource details and cleanup rules are covered in the pages linked below.