Containers

A Container is the direct-management option for one Docker runtime. Gateway stores its configuration and access relationships, while the selected Docker daemon starts and supervises the actual process. Use a Container when blue/green release slots or multi-service project ownership are not required.

When a Container is the right owner

Choose a Container for a single service whose restart, update, and recovery can be managed as one runtime. It works well for internal tools, agents, stateless services, and workloads with a simple persistent-volume relationship. The application owner remains responsible for deciding whether replacing the process is safe and whether its data requires a backup or maintenance window.

Choose a Deployment instead when a release must be prepared and health-checked before traffic moves, with a retained rollback candidate. Choose Compose when several services, networks, variables, and volumes must change under one revision. A Container is deliberately direct; Gateway does not invent an application release strategy around it.

Success means more than a running state. The expected health check must pass, the application must listen on the selected port, its Route or private connection must work, and persistent data must remain attached after a recreate. Define those checks before the first production update.

Before you begin

You need access to the target Docker node and permission to create or change the Container. Confirm that the image is available from a permitted registry, the node has capacity, and the requested runtime is supported. Review ports, Routes, database bindings, managed volumes, and secrets before choosing a name: those relationships can affect later rename, migration, or deletion work.

New host bind mounts are rejected. Use Gateway-managed local volumes for new persistent data. Legacy bind mounts can remain during an ordinary update, but once removed they cannot be added back through Gateway.

The Default runtime is available on supported Docker nodes. The secure gVisor runtime requires a healthy reported capability and cannot be combined with GPUs, devices, host bind mounts, migration, or archive export.

Create and update a Container

1. Select the Docker node and image, preferably an immutable digest for a production workload.
2. Set the command, entrypoint, environment, encrypted secrets, labels, ports, restart policy, resource limits, health checks, and managed volumes.
3. Review the resolved configuration and create the Container.
4. Follow the create Task until the daemon reports the runtime state.
5. Check health, logs, and any Route or private database connection before sending application traffic.

Use Recreate when a runtime configuration change requires a replacement process. Gateway preserves the stable resource identity while creating the intended runtime again. Use Duplicate when you need a separate resource with independent access grants and lifecycle history. Use Rename only after reviewing dependent Routes, bindings, and integrations.

Verify and operate

The detail view is the operational record: confirm the desired and observed state, health result, image identity, recent Tasks, and logs. Use console or file access only for the scopes granted to you, and avoid using an interactive console as the normal deployment path.

After a restart or daemon reconnection, Gateway should reconcile the saved desired state. If the Container is running but cannot serve traffic, check its health check, listening port, Route target, environment, and application log in that order.

Failure handling and cleanup

An image pull failure, unavailable registry credential, port conflict, invalid mount, unsupported runtime capability, or exhausted node resource must be corrected before retrying. The Task history identifies the stage that stopped; retries without changing the prerequisite usually repeat the same failure.

Before deletion, inspect Routes, database bindings, grants, volumes, source settings, and exported data. Deleting the Container removes its resource grants, so a later Container with the same name does not inherit access. Volume deletion is a separate destructive action; retain or back up persistent data before removing either resource.

Operator details: recreate and recovery

A configuration change that affects image, command, environment, mounts, runtime, ports, limits, or restart behavior can require recreation. Recreation replaces the Docker runtime while preserving Gateway’s stable Container identity and supported relationships. Existing in-process sessions are interrupted, so schedule the operation or use a Deployment when interruption is unacceptable.

Before recreation, record the current image digest, health result, attached volumes, Route and binding state, and any application-specific drain requirement. After the Task completes, compare the new runtime with the saved desired state and test the real client path. If startup fails, restore the previous known-good configuration or image and recreate again; do not edit the failed Docker object outside Gateway.

If the Docker Node disconnects during an operation, wait for a fresh inventory after reconnect before retrying. The host may have completed the runtime action without acknowledging it. If a Container is missing but its desired state still exists, use the supported reconcile or recreate path. Deleting and recreating the Gateway record changes ownership and grants and should not be the first recovery action.

Console and file access are incident and inspection tools, not a substitute for reproducible configuration. Changes made only inside a running container can disappear on the next recreate and should be moved into the image, managed configuration, or persistent volume.