How Areca works

Areca separates writing from publishing. Editors change drafts freely. Nothing reaches the public website until someone approves the content and goes live. This page explains the model behind that split, so the rest of the documentation makes sense.

Data modelCopy Anchor Link

Content is organised in four levels:

Collections belong to the website, not to the CMS. A developer declares them in the website's areca.config.ts and pushes them to the CMS. Agency admins can also edit them in the CMS, but a push overwrites those CMS edits. Pushing a schema changes what editors can fill in. It does not create pages on the website, and the website's code still decides how an article is rendered.

The Library belongs to the client. All of a client's sites share its files. Files uploaded to the Library have public URLs, including files attached to drafts. See Library before you upload anything confidential.

Entry versions and statusesCopy Anchor Link

Each entry can hold several versions at once. Areca tracks four:

An entry can also be Archived. Archived entries stay in the CMS and are left out of the website.

Some rules follow from this model:

• Saving a draft never changes the public website.
• Editing an entry that is ready or live changes its draft. The ready or live version stays as it was until someone marks the new draft ready.
• When the draft differs from the ready version, the CMS shows that the entry was edited since it was ready.
• Entry history restores authoring data for one entry. Restoring a release rolls back the whole site.

See Statuses and review for how these states look in the editor.

SchedulingCopy Anchor Link

Scheduling freezes the draft and its slug at the moment you schedule it, after the required fields are checked. Later draft edits do not change the scheduled version.

When the scheduled time arrives, the CMS starts a release for the site, just as if someone had selected Go live. The scheduled version becomes live only when that release succeeds. If the release fails, the entry stays scheduled, the failure is recorded in the site's activity, and the CMS retries after a cooldown of about ten minutes. Owners can cancel a schedule before it runs.

See Scheduling for the editor workflow.

Releases and snapshotsCopy Anchor Link

A release is one publication of a whole site. Each Go live creates a release that includes every ready change on the site, not only the entry you just changed. The CMS:

1. Builds a snapshot: the content of every enabled collection, with references and asset URLs resolved.
2. Stores the snapshot with a publication ID and a content hash.
3. Never changes it afterwards.

Because snapshots are immutable, a release always shows exactly what was published. The CMS keeps earlier releases so that you can restore one later.

In the Go-live panel, releases show one of these states:

Demo releases are labelled as demo. They are available for local builds but are never production live.

The go-live pipelineCopy Anchor Link

When an owner or agency admin selects Go live, the CMS works through these stages:

1. Validate. The CMS checks every enabled collection: required fields, slugs, references, assets, rich text, SEO data and route collisions. Problems are listed under Fix these first, and nothing is built until they are resolved.
2. Snapshot. The CMS saves the immutable snapshot and queues a build. A new request replaces any build for the same site that is still queued.
3. Build. The website's build pulls the snapshot with areca pull. The snapshot is pinned to this release, so the build cannot pick up later drafts.
4. Deploy. For production sites, the CMS asks the deployment provider to deploy the site. Only one deployment can be active per site at a time.
5. Health check. The CMS calls the site's health URL and checks that it reports the publication ID it just built.
6. Live. The release becomes live. If any step fails, the previous live release stays live.

Production and Demo sites differ in steps 4 and 5:

If the CMS loses track of a deployment request, it reconciles the request with the provider instead of sending it again, so a retry cannot deploy twice.

RollbackCopy Anchor Link

A rollback restores an earlier release that was live. The CMS creates a new release from the saved snapshot of that earlier release and queues a high-priority build. A rollback does not use today's drafts, does not delete newer drafts, and does not change the website's source code, database migrations or provider settings. See Going live for the steps.

How websites use contentCopy Anchor Link

A website uses the CMS in three ways. Each uses a different credential.

Because the site renders from a pulled snapshot, a change to a published entry appears on the website only after a successful release and a new build.

Assets work differently. A snapshot stores the asset URLs as they were when it was built, so the CMS must stay reachable at the address it advertises. A file used by a retained release cannot be deleted from the Library. See Asset retention.

For the credentials in detail, see Tokens.

RolesCopy Anchor Link

Access depends on the role a person holds:

Some sensitive actions also ask for a fresh authenticator code. See Roles and permissions and Two-factor and step-up.

RelatedCopy Anchor Link

• Quickstart takes you through a first publish.
• Glossary defines every term used in the documentation.
• Self-hosting overview explains what you need to run Areca.