Quickstart

Start the CMS and create the first adminCopy Anchor Link

Run the local demo stack. It starts the CMS, PostgreSQL, Redis, S3-compatible storage and an email inbox.

cd docker
cp .env.example .env

Open .env and replace the example secrets. Generate them with:

openssl rand -hex 32     # BETTER_AUTH_SECRET
openssl rand -base64 32  # DOKPLOY_CREDENTIALS_ENCRYPTION_KEY

Then start the stack:

docker compose up -d --wait

Open http://localhost:3000/setup. Enter the setup token. If you did not set SETUP_TOKEN in .env, read the generated token from the log with docker compose logs cms. Then enter your name, email and a password of at least 8 characters, and select Create admin account.

The first admin must turn on two-factor authentication. Scan the QR code with an authenticator app, enter a code to confirm, and store the recovery codes somewhere safe. The CMS then opens the Agency workspace.

Create a client and a siteCopy Anchor Link

A client is the organisation you build for. A site belongs to a client and holds its content.

In the Agency workspace, select New client, enter a name such as Acme, and select Create client. Check the suggested slug before you save it: it cannot be changed later.

On the client page, open the Sites tab and select New site. Enter a Site name such as Acme Website, keep the suggested Site key (for example acme-website), and set the Production URL. For local work, http://localhost:3001 is the default. Select Create site.

The next screen shows the site token. It is shown only once.

Connect the website and push the schemaCopy Anchor Link

These commands run in your website project, not in the CMS repository. If you do not have a website yet, create a small TanStack Start or Node.js project first.

pnpm add @areca-cms/site-sdk
pnpm exec areca init

areca init asks for the CMS URL (http://localhost:3000), the site token and the site key. It creates areca.config.ts, a .env.example, a gitignored .env.local, and an empty src/generated/content folder.

Declare the content your website needs in areca.config.ts. This example defines one collection called articles:

import { defineSiteContent } from '@areca-cms/site-sdk'

export default defineSiteContent({
  siteKey: 'acme-website',
  collections: {
    articles: {
      route: '/blog/$slug',
      label: 'Articles',
      fields: [
        { key: 'title', label: 'Title', type: 'text', required: true },
        { key: 'body', label: 'Body', type: 'richtext' },
      ],
    },
  },
})

Pushing the schema needs a separate schema-write token. In the CMS, open the site, go to Settings › Developer, and select Rotate schema token under Schema-write token. Copy the token and add it to .env.local, next to the values that areca init wrote:

ARECA_SCHEMA_TOKEN=<your-schema-token>

Push the content model to the CMS:

pnpm exec areca manifest push

Back in the CMS, Settings › Content now lists Articles, and Settings › Developer reports one content type synced from the site project. The website build uses only the site token. Keep the schema token out of builds and public code.

Write an entry and mark it readyCopy Anchor Link

Open the site's Articles collection and select New article. Enter a title such as Welcome to Acme, which fills in the slug, and add some text to Body. The editor saves as you type. Select Save to save immediately.

Saving does not publish anything. To include the entry in the next release, select Mark as ready. The entry now shows the Ready status.

If you are not an owner of the client, the publish controls are disabled and explain why. An owner or agency admin must mark the entry ready.

Go liveCopy Anchor Link

Going live creates a release: a frozen copy of every ready change on the site. Choose a mode in Settings › Deployment first.

pnpm exec areca pull
pnpm dev