Deployments

A deployment is a single version of a service running in a container. Every time you push code, pull a new image, or click “Deploy”, Clank creates a new deployment record, builds or pulls the image, starts a container, and runs health checks. The previous deployment stays running until the new one is verified healthy.

Deployment lifecycle

PENDING → BUILDING → DEPLOYING → HEALTH_CHECKING → ACTIVE
                                                  ↘ FAILED

1. PENDING — Deployment created, waiting for a worker to pick it up.
2. BUILDING — Cloning the repo and building a Docker image (git deploys only; skipped for Docker image deploys).
3. DEPLOYING — Starting the container with environment variables, volume mounts, resource limits, and Traefik routing labels.
4. HEALTH_CHECKING — Container is running. Clank is probing the health check endpoint to verify the service is ready.
5. ACTIVE — Health checks passed. Traffic is routed to this container.
6. FAILED — Something went wrong (build error, container crash, health check timeout). The failed container is stopped. If a previous deployment was running, it continues serving traffic.

Other statuses

• SUPERSEDED — A newer deployment replaced this one. The old container has been removed.
• ROLLED_BACK — This deployment was the target of a rollback. A new deployment was created from its image.
• CANCELLED — Deployment was cancelled before completing.

Blue-green deploys

For services that have a health check path and no persistent volumes, Clank uses blue-green deployment — zero-downtime with automatic rollback on failure.

How it works:

1. The old container (“blue”) keeps serving traffic.
2. A new container (“green”) starts alongside it with the same Traefik routing labels.
3. Clank runs health checks against the green container only.
4. If health checks pass: Traefik begins routing to the green container. After a brief stabilization period, the blue container is stopped and removed. The old deployment is marked SUPERSEDED.
5. If health checks fail: The green container is stopped and removed. The blue container continues serving traffic as if nothing happened. The deployment is marked FAILED.

Users experience no downtime in either case.

Note

Blue-green is automatically disabled for services with persistent volumes (databases, caches). Running two instances of a database against the same volume can cause data corruption. These services use recreate mode instead — the old container stops before the new one starts.

Recreate deploys

Services that have persistent volumes or no health check path use recreate mode:

1. Stop and remove the old container.
2. Start the new container.
3. If a health check path is configured, run health checks. Otherwise, mark as ACTIVE immediately.

There is a brief downtime window between stopping the old container and the new one becoming ready.

Health checks

When a service has a health check path configured (e.g., /health or /), Clank probes it after the container starts:

Setting	Default	Description
Path	/health	HTTP endpoint to probe
Retries	3	Number of attempts before failing
Interval	10s	Time between retry attempts
Timeout	5s	Max time to wait for a response
Startup grace	30s	Wait time before the first probe

Any HTTP response (2xx, 3xx, 4xx) counts as “healthy” — it means the process is listening. Only connection failures and timeouts count as unhealthy.

When the health check path is empty, Clank skips health checking entirely and marks the deployment as ACTIVE as soon as the container starts. This is the right choice for databases, caches, and background workers that don’t serve HTTP.

See Health Checks for more detail.

Rollback

Rolling back creates a new deployment from a previous deployment’s image. It is not a revert — it’s a forward deploy using an older image.

What rollback copies from the target deployment:

• Docker image tag
• Port and health check configuration
• Resource limits (CPU, memory)
• Domain assignments
• Volume mounts
• Environment variable snapshot (the exact env vars at the time of the original deploy)

What rollback does NOT do:

• It does not restore the current service configuration. If you changed env vars since the original deploy, the rollback uses the old env var snapshot, not the current values.
• It does not skip health checks. The rolled-back deployment goes through the full lifecycle (DEPLOYING → HEALTH_CHECKING → ACTIVE).

Caution

Rollback requires the original image to still be available. Git-built images stored only on the local Docker daemon may have been cleaned up. Push important deployments to the registry to ensure rollback capability.

Triggered by

Every deployment records how it was triggered:

Trigger	Description
MANUAL	User clicked “Deploy” in the dashboard
GIT_PUSH	Automatic deploy triggered by a git push to the watched branch
ROLLBACK	Created by rolling back to a previous deployment
PR_PREVIEW	Preview environment for a pull request
CLI	Deployed via the clank deploy CLI command
REDEPLOY	Redeployed the same image with fresh service configuration

Next steps

• Health Checks — Configure health check behavior.
• Persistent Volumes — Add storage that survives redeployments.
• How to Roll Back — Step-by-step rollback instructions.