Projects and Services

A project groups related services together. A service is the thing that actually runs — a container built from a Git repo, pulled from a Docker image, or deployed from a template. Every deployment targets a service, and every service belongs to a project.

Projects

A project is an organizational container. It holds one or more services that make up an application. A typical project might contain a web frontend, an API backend, and a PostgreSQL database — three services, one project.

Each project has:

A name and an auto-generated slug (used in container names, volume names, and network names).
A team it belongs to. All team members can view and manage the project’s services.
A Docker network (clank-project-{slug}) that isolates its containers. Services within the same project can reach each other by container name. Services in different projects cannot communicate unless you configure it explicitly.
A canvas view in the dashboard — a visual layout where you can arrange and connect your services.

Projects support soft deletes. Deleting a project marks it as deleted but does not immediately remove running containers. Active deployments must be cleaned up first.

Services

A service is the deployable unit. It defines what to run, how to run it, and where to run it.

Three source types

Every service has a resource_type that determines where the container image comes from:

Git (git): Clank clones your repository, auto-detects your framework (Node.js, Python, static SPA), generates a Dockerfile if one does not exist, builds the image, and deploys it. You configure the repo URL, branch, and optionally a custom Dockerfile path.
Docker image (docker_image): Clank pulls a pre-built image (public or private registry) and runs it directly. No build step. Useful for off-the-shelf software like Redis, PostgreSQL, or any image you build in your own CI pipeline.
Template (template): A pre-configured combination of image, environment variables, volume mounts, resource limits, and health check settings. Templates are the fastest path to running common software (WordPress, n8n, Ghost, Supabase, and others).

Service settings

Setting	Default	Notes
`port`	`8080`	The port your application listens on inside the container.
`health_check_path`	`/health`	HTTP path Clank hits to confirm the container is healthy. Set to empty string for databases and other non-HTTP services.
`health_check_interval_s`	`10`	Seconds between health check attempts.
`health_check_retries`	`3`	Failed checks before the deployment is marked failed.
`build_timeout_s`	`600`	Max seconds for the Docker build step (git services only).
`deploy_timeout_s`	`300`	Max seconds for the container to pass health checks after starting.
`cpu_limit`	`0.5`	CPU cores allocated (e.g., `0.5` = half a core, `2` = two cores).
`memory_limit_mb`	`512`	Memory limit in megabytes.
`auto_deploy`	`true`	When enabled, pushes to the configured branch trigger a new deployment automatically.
`is_public`	`true`	Controls whether the service is exposed through an endpoint or only accessible on the Docker network.

Server assignment

A service can run on the platform server (the machine hosting the Clank control plane) or on a remote server running the Clank agent. This is controlled by the server_id field:

server_id is null: The service deploys locally. The Dramatiq worker builds and starts the container on the platform server.
server_id is set: The service deploys remotely. The control plane sends a gRPC command to the agent on the target server, which pulls the image and starts the container there.

You assign a server when creating the service or change it later in the service settings.

Persistent volumes

Services that need to store data across redeployments use named Docker volumes. Volume mounts are configured as a JSON array on the service:

[
  { "name": "clank-myproject-postgres-data", "mount_path": "/var/lib/postgresql/data" }
]

Volume names follow the format clank-{project_slug}-{service_slug}-data. Database templates (PostgreSQL, MySQL, MongoDB, Redis) configure volumes automatically. For custom services, you set the mount path in the service settings.

Environment variables

Each service has its own set of environment variables, encrypted at rest with Fernet encryption. Variables marked as secrets are redacted in API responses (shown as ********). You can create, update, and delete variables individually or in bulk.

At deploy time, the current environment variables are snapshotted and stored on the deployment record. This means a running deployment always has the exact variables it was started with, even if you change the service’s variables afterward.

How services relate to deployments

A service is the desired state — what you want to run. A deployment is an immutable snapshot of a specific run attempt. When you trigger a deploy, Clank creates a new deployment record that captures the image tag, environment variables, volume mounts, domains, and resource limits at that moment.

The deployment moves through these statuses:

PENDING — Created, waiting for a worker to pick it up.
DEPLOYING — Container is being built (git) or pulled (image), then started.
HEALTH_CHECKING — Container is running, Clank is verifying the health check endpoint responds.
ACTIVE — Health checks passed. This deployment is now live.
FAILED — Something went wrong (build error, health check timeout, container crash).

When a new deployment reaches ACTIVE, the previous active deployment is marked SUPERSEDED. The service’s current_deployment_id pointer updates to the new one. Only one deployment per service is ACTIVE at a time.

Next steps

Servers and the Clank Agent — Understand where your services run.
Endpoint Access Modes — Make your services reachable from the internet or your private network.