Areca DocsPublishing pipeline
How a Go live request moves through the queue, build leases, deployment (Dokploy or Cloudflare) and health check, and how to recover a stuck or uncertain release.
Editors press Go live in the CMS, but the release itself is carried out by the publishing worker that runs inside your CMS instances. This page follows a release from the operator's side: what the worker does at each stage, what each outcome means for the live site, and what to do when a release stops moving. For the editor's view, see going live.
How a release moves
Each release creates a publication (the release record) and a build job (the work to produce it). The publication moves through these states: pending, building, live, failed, superseded, rolled_back. Demo sites end in demo instead of live. The build job moves through queued, building, validating, deploying, then succeeded, failed or cancelled.
Request. An owner presses Go live. The CMS checks that a production site has a deployment target (a Dokploy application or a Cloudflare project) and a health check URL. If either is missing, the request is rejected with the message "Production publishing requires a deployment target and a publication-aware health URL." Otherwise it freezes the content into an immutable snapshot, and creates a publication in pending and a build job in queued. Only one job can be active for a site at a time.
Queue. The worker claims queued jobs, highest priority first, then oldest first. Jobs for different sites run in parallel, up to WORKER_CONCURRENCY per process. See urgent releases and rollback for the two priority cases.
Lease. A claimed job holds a 60-second lease, which the worker renews every 15 seconds. The job log shows each stage: building, then validating (the snapshot is checked), then deploying. If the lease expires, because the worker stopped or lost its database connection, the job is recovered as described below.
Dispatch. The worker records in the database that it is about to contact the deployment provider. For Dokploy, it sets ARECA_SNAPSHOT_ID to the publication ID (as a build argument for Dockerfile builds, or as an environment variable for Railpack and Nixpacks builds) and sends one deploy request, and the deployment is tagged areca:<jobId>. For Cloudflare, it writes ARECA_SNAPSHOT_ID as a build variable on the project, then starts one build. See how the snapshot reaches the build and how the snapshot reaches a Cloudflare build.
Wait for the build. The worker checks the deployment in the provider every 5 seconds, for up to 15 minutes. A status check that fails with a network error or an HTTP 408, 429 or 5xx response is retried for about 30 seconds before the release is treated as uncertain. If the provider reports an error, the release fails with Deploy error. For Cloudflare, a Pages deployment is done when its deploy stage succeeds, and a Worker build when it ends with the outcome success.
Health check. The worker polls the health check URL every 5 seconds, for up to 2 minutes. It needs a 200 response whose publicationId matches the release. If it does not get one, the release fails with Health check failed.
Go live. The new publication becomes live, and the previous live publication becomes superseded. Any scheduled entries in the release are published at this point. For a demo site, the publication is marked demo instead, and no deployment or health check takes place.
Outcomes
| Outcome | Publication | Previous release | What to do |
|---|---|---|---|
| Succeeded | live | Marked superseded | Nothing. |
| Failed before the deploy request was sent | failed | Stays live | Fix the cause (for example a missing target, or a rejected deploy request), then press Go live again. |
| Failed after the deploy request, with a deployment error or failed health check | failed | Stays live | Read the build log in the provider and the job log, fix the cause, then publish again. |
| Uncertain: the deploy request may have been accepted | Blocked | Stays live | Reconcile the job. See uncertain deployments. |
| Cancelled | superseded | Stays live | Only queued jobs can be cancelled, with Cancel job. |
| Lease expired | failed, or blocked if the deploy request had been sent | Stays live | Retry if no deploy request was sent. Otherwise reconcile. |
A failed release never takes the live site down on its own. The previous release stays live unless a new release succeeds.
Uncertain deployments
A release is uncertain when Areca cannot tell whether the deployment provider accepted the deploy request. This happens when the request times out or gets an ambiguous response, or when the worker stops after sending the request but before it records the result. A status check that is still failing after about 30 seconds of retries also makes it uncertain. While a job is uncertain, the site is blocked: no new Go live can start for it.
Areca never sends a second deploy request to resolve an uncertain job. Recovery is manual.
Note the IDs. Open the failed job in Go live and note its job ID and publication ID.
Check the provider. For Dokploy, look in the application's deployment history for a deployment titled areca:<jobId> whose description contains the matching publication ID and snapshot hash. For applications built from a Git provider, Dokploy replaces that title and description with the commit message and Commit: <sha>. Areca then matches the one deployment created after the dispatch, if there is exactly one. For Cloudflare, look in Workers & Pages › the project › Deployments for a Pages deployment started by the API (type ad_hoc) on the production branch, or in the Worker's Builds for a build started by the API (trigger source manual) on the same trigger and branch. If there are several matches, check the history by hand. Do not start a replacement build while the original might still be running.
Check the deployment status. If you find the deployment, or if the provider's connection has been restored since the failure, an owner selects Check deployment status on that job. Areca resumes watching the same deployment, then checks the health response for that publication.
If no deployment matches, investigate. A missing record does not prove the request was rejected. Keep the block in place while you find out what happened, for example by checking the provider's logs and whether any build is still queued or running.
Release the block, if you must. Once you have confirmed that every possibly running or queued deployment or build for this request has been stopped or cancelled in the provider, an agency admin can select Release publishing block. Enter the reason you verified this, for example at least ten characters describing the check you made, and confirm. The release is marked failed, the site is unblocked, and the action is recorded in the audit log. Areca does not deploy again, and it never marks the uncertain release live.
Releasing the block does not stop the deployment
Releasing the block only unblocks Areca. If a deployment or build is still running in the provider, it may finish later and serve content from the uncertain release. Stop or cancel it in the provider's dashboard first, and only then release the block.
Owners can check the deployment status but cannot release the block. Only agency admins can do that.
The server refuses to change the publishing mode or the deployment target of a site while one of its jobs is queued, running or uncertain. It also refuses to change the Dokploy host or the Cloudflare account of a client while any of its sites has such a job. The Deployment tab locks these settings in the same cases. Recovery uses the connection that was saved for the job.
Urgent releases
When you press Go live, an owner can choose Urgent — skip the queue. An urgent request gets a higher priority, so it is claimed before other sites waiting to go live. It does not stop running builds, and it cannot run alongside another build for the same site. If the same site already has a job running, the urgent job waits for it.
Scheduled releases
Entries can be scheduled to go live at a set time. A scheduler inside the CMS checks about every 15 seconds for scheduled entries whose time has passed. For each site with due entries, it starts a release if no job is already active for that site. The release is recorded as started by system ("Started automatically"). The audit log also records who scheduled the entries.
If a scheduled release cannot start, for example because the production target is missing, the entries stay scheduled. Areca records a publication.scheduled_failed event in the audit log and waits at least 10 minutes before trying that site again. The areca_scheduled_entries_overdue metric counts entries that are past their time. The suggested alert fires when they stay overdue for 30 minutes.
To stop a scheduled entry from going live, cancel its schedule in the editor. See scheduling.
Rollback
Every release that was live can be restored from the Releases list with Restore this version. Only owners can do this.
A rollback does not rebuild from current drafts. It creates a new publication from the stored snapshot of the earlier release. That publication is queued with a high priority, goes through the same deploy and health check as any other release, and gets its own ID. It does not publish any scheduled entries, so it cannot pull unrelated content live.
If the rollback fails, the release that was live before it stays live. A publication that was never live, or a demo publication, cannot be a rollback target.
When a release is stuck
Start with the job log. In Go live, open the release and select View log. The last line shows the stage the job reached.
The job stays queued.
- Check the
queuecheck in/api/health/ready, and theArecaBuildQueueStuckalert. - Check that the CMS has
WORKER_ENABLEDon, and that the worker is not already runningWORKER_CONCURRENCYjobs. - Look for worker errors in the CMS logs.
The job stays deploying.
- Check the deployment status in the provider. In Dokploy, its build log shows clone and build errors, for example a deploy key that cannot clone the repository. In Cloudflare, check the Pages deployment or the Worker build in the dashboard.
- Wait up to 15 minutes. If the wait runs out, the release becomes uncertain, and you reconcile it.
The job fails with Health check failed.
- Open the health check URL in a browser or with
curl. It must return JSON with the new publication ID. If it returns the old ID, the new build is not serving. Check thatARECA_SNAPSHOT_IDis set (as a build argument for a Dokploy Dockerfile build, an environment variable for a Dokploy Railpack or Nixpacks build, or a build variable in Cloudflare), and that a Dokploy Dockerfile declares it after the SDK build. - If the URL uses a LAN address, check the two switches in HTTPS and private addresses.
- For Dokploy, check that the host publishing port maps to the container's port and that the update order is stop-first.
- For Cloudflare, check that the build command runs
areca pullbefore the build, and that the health route is served by the build. See Cloudflare builds.
The job fails with Deploy error.
- Read the deployment log in Dokploy for the failing build, or the build log in Cloudflare. In Dokploy, a cloning error usually points to the deploy key or the repository URL.
The site is blocked and you see a message about an unknown outcome.
- Follow uncertain deployments.
Failures keep happening.
- Check the
ArecaBuildJobsFailingalert and the failed job counts in the metrics. - Check troubleshooting for common deployment and sign-in errors.
Related
- Deployment targets (Dokploy and Cloudflare): the provider setup, credentials and health check rules.
- Operations and monitoring: metrics, alerts, logs and worker shutdown.
- Going live: the editor's view of a release.
- Deployments: assigning a deployment to a site.
- Scheduling: scheduling entries for a future release.