Deploying and running an environment

Deploying is what turns a project's description into running containers on a server. It happens at the environment — the project holds the compose document; the environment is one copy of it, on one server (or a set of servers), with its own hostnames, storage and variables. This chapter covers the whole life of an environment: choosing where it runs, previewing what will be sent, deploying and redeploying, stopping and starting, destroying, reading logs and history, and what every refusal means.

The model

A deploy is a command the control plane sends to the daemon on the target server. The control plane does the thinking — it merges the project compose with the environment's overlay, resolves variables and secrets, schedules services across servers, allocates addresses, and compiles one runtime compose.yaml per participating server. The daemon does the doing — pulls images, checks out and builds source releases, writes the files, and runs Compose. What you see in the app is the command's progress, polled until it reaches a terminal state.

Three consequences shape how the buttons behave:

• Nothing runs until a server is chosen. An environment resolves its server from its own pin or the project's default; without one, Deploy is disabled and points you at the Hosting tab.
• Preview is free; Deploy is a command. Preview shows exactly what would be sent without sending it. Deploy enqueues a command that the app tracks to completion.
• The daemon is the source of truth for status. Container status is what the daemon last reported; the app refreshes it after each tracked command and on Refresh, not on a timer.

Before you begin

• A connected server in the organization (Servers shows Online).
• A saved compose document with no blocking lint findings.
• For any site or Node app in the document, a system user assigned — Deploy stays disabled with No system user — assign one in Bindings until then.
• Manage rights on the organization.

Placement and scheduling

The pin is the anchor. Services that declare deploy.replicas or deploy.placement.* are placed by the planner across the organization's connected servers, respecting host-port conflicts, co-location and spread constraints and the per-server replica cap; services on more than one server must share a spanning (driver: overlay) network, which TurboFabric carries. Preview ▾ → Prepared compose shows one block per server whenever the plan spans more than one host.

Any connected server is a valid target, including the host a self-hosted control plane runs on. A one-server installation can deploy to itself.

Preview

Prepared preview runs the same validation Deploy does, so a refusal shows up here first — same code, same message.

Deploy, redeploy, cacheless

A redeploy with no change is a no-op: the platform hashes the compose document together with each source service's resolved commit, and the daemon skips work whose hash it has already applied. Push a commit or change the document, and the same button does real work.

Health-check gates

Each service carries a Health check policy (its settings page): disabled, warn, or required. At deploy, a service with policy required and no healthcheck in its compose refuses the deploy outright (health_check_missing with required: true). A service with policy warn and no health check stops the deploy once with a prompt naming the services; confirming sends the deploy again with the warning acknowledged.

Deploy strategies

An environment has a deploy strategy, which decides how the new version replaces the old one.

A sequential deploy goes in this order:

1. Prepare — networks, image pulls and source builds. If this fails, nothing has been stopped and the old version is still serving; the deploy simply fails.
2. Stop the old version. Services that keep data on a writable volume (databases and the like) stay running so a migration has something to talk to.
3. Migrate — any pre-deploy command runs. From here on the schema may have changed.
4. Start the new version, then the health gate: every service must be healthy. A container with a healthcheck must report healthy; one without must stay running for a short stable window; a one-shot service must exit cleanly; a container that exits with an error or keeps restarting fails the gate. The gate gives up after healthTimeoutSeconds.

How a sequential deploy that does not finish ends is shown in Deployment history instead of a plain Failed:

An environment that declares migrations: breaking is treated as past the point of no return from the start, so a failed health gate there is always Needs attention. A first deploy has no previous version to go back to, so a failure is an ordinary failure.

The strategy is set on the environment's options through the API (there is no screen for it yet), next to the compose overlay:

A project's options may carry the three numbers as defaults for its environments; an environment's own value wins. Send null for a key to clear it. A value out of range, or a key that does not belong (a project cannot set deployStrategy), is refused with deploy_options_invalid and the field is named. Preview (GET /environments/:id/deploy-preview) reports the strategy requested, the one that would really run (effectiveStrategy), the migration status and, when the two differ, the fallbackReasons.

Rolling deploys across servers

An environment whose services land on more than one server (through deploy.replicas or deploy.placement, see Placement and scheduling) is deployed to each of them. A sequential deploy (and bluegreen, which runs as sequential for now) then updates the servers in batches, sized by the Compose deploy.update_config.parallelism of its services:

services:
  web:
    deploy:
      update_config:
        parallelism: 2   # two servers at a time

Only the first batch is queued. Each next batch is queued when every server in the batch before has applied the deploy. A single-server deploy is unchanged. The deploy response and the preview report rollout as { parallelism, batches }.

When a batch fails. The first server that fails or times out stops the rollout. Servers that have not started are marked failed in Deployment history with the reason rollout stopped … this server was not started, and their commands are cancelled. Servers that were already running finish. Servers that updated in an earlier batch stay on the new version: nothing rolls them back, so the environment can be left on two versions until you fix the cause and deploy again. Each server's own sequential deploy still rolls back to its previous version when it can (see the outcomes above).

An inplace environment ignores parallelism: it updates every server at once and reports parallelism: 0. A compose document that sets it gets a non-blocking warning from Preview and Deploy (deploy.update_config.parallelism is ignored: this environment deploys inplace); set the environment's deployStrategy to sequential to use it.

Start, stop, restart, destroy

Stop and Start only touch existing containers, so they stay available even when Deploy is disabled for a missing system user. Destroy is the one that loses data; the app asks twice.

Container status and logs

The environment's Overview lists each service's containers with a status badge from the daemon's last report. Refresh asks again.

Logs on a container opens a live tail of its stdout and stderr, streamed from the host on demand. It is never stored: close the panel and it is gone. For the record of what a deploy did, see the next section.

Deployment history

Deployment history on the environment's Overview lists past deploy attempts with their outcome, who or what started them (a person, the system, or Push to <branch> with the short commit when a git push did) and, for each, the transcript the daemon produced — image pulls, builds, the Compose output — kept for 90 days by default (an operator can change TURBOPANEL_EXECUTION_LOG_RETENTION_DAYS).

A sequential deploy also names the engine it ran (Sequential or In place) and, when it did not finish, Rolled back or Needs attention with the reason; see Deploy strategies.

A deploy that never finished is recorded as stalled, with one of two reasons:

Reference

POST /environments/:id/deploy

Response: the queued command's id and the URL to poll. GET /environments/:id/deploy-preview returns the prepared shape without enqueueing.

POST /environments/:id/lifecycle

{ "action": "start" | "stop" | "restart" }. Operates on existing containers only.

POST /environments/:id/stop

Destroy. Removes containers and volumes, tears down hostnames and releases.

Command statuses

queued → dispatching → sent → acked → running → one of succeeded, failed, timed_out, cancelled. Commands carry a delivery deadline; one the daemon never picks up becomes timed_out and is recorded in history as stalled with the reason above.

The prepared shape

Errors

Every refusal carries a stable error code and, where useful, a message and the offending names. Grouped by what to do about them.

Fix the document

Fix the placement or the servers

Fix hostnames or TLS

Acknowledge and retry

Related

• Projects and environments — the environment's pin and overlay.
• Writing compose — the document, the field policy, the linter.
• Deployment logs — how transcripts are stored and retained.
• Container logs — why the live tail is never stored.
• Datacenter networks — spanning networks and TurboFabric.