Your first project

A Meridian project is a directory: configuration under config/, templates under templates/, seed content under seed/ and static files under public/. This page creates one, puts it in a database and signs you in to the admin.

Each step needs the one before it:

flowchart LR
  init["init<br/>writes the files"] --> check["check --no-db<br/>no database"]
  check --> migrate["migrate up<br/>engine tables"]
  migrate --> apply["schema apply<br/>your types and sites"]
  apply --> seed["seed apply<br/>the home page"]
  seed --> dev["dev up<br/>serves the site"]
  migrate --> user["user create<br/>admin sign-in"]

You need the binary and a PostgreSQL database (Install).

Create the projectCopy Anchor Link

engine-dmo init my-site

created a project in /home/you/my-site from the starter (...)

guidance for coding agents: AGENTS.md, .claude/skills/meridian-project/SKILL.md, .claude/skills/meridian/SKILL.md

editor support: config schemas in .meridian/schema, mapped for zed and vscode

next:
  export DATABASE_URL=postgres://...
  engine-dmo migrate up --project /home/you/my-site
  engine-dmo schema apply --project /home/you/my-site
  engine-dmo seed apply --project /home/you/my-site
  engine-dmo serve --dev --project /home/you/my-site

init takes the directory as its argument (the current directory when omitted) and refuses a directory that already holds config/engine.yaml.

What the starter containsCopy Anchor Link

config/engine.yaml reads everything that differs between machines from the environment:

engine:
  version: "1.x"
  environment: ${ENVIRONMENT:-development}

server:
  listen: ${LISTEN_ADDR:-127.0.0.1:8080}
  base_url: ${BASE_URL:-http://localhost:8080}

database:
  url: ${DATABASE_URL}

logging:
  format: ${LOG_FORMAT:-text}

storage:
  driver: filesystem
  filesystem:
    root: ./storage

config/locales.yaml declares one locale, en. Set its timezone and currency to your own before you add content; the starter uses Etc/UTC and EUR:

locales:
  available:
    - code: en
      id: loc_3990wq8rss
      label: English
      source: true
      default: true
      timezone: Etc/UTC
      currency: EUR

config/sites/main/site.yaml declares the one site, answering on localhost and localhost:8080, and routes.yaml routes pages and names the home page:

routes:
  - type: page
    id: rte_8397jasp17
    uri: "/{slug}"

home: { type: page, slug: home }

The id: values are written by init and are different in every project; never copy them between projects. Stable ids explains why.

config/access/grants.yaml gives the administrators group the built-in owner role, so the first staff user you create can do everything (Users, roles and permissions):

grants:
  - { group: administrators, role: owner }

seed/seed.yaml names the seed and lists locales: [en]. That list limits only the analytics a seed can generate; document values load in every locale a seed file gives, so a new locale needs its values in the documents, not in this list.

templates/_shared/page/entry.html renders a page:

{% extends "base.html" %}
{% block body %}
<h1>{{ entry.title }}</h1>
{% endblock %}

The core page type has only two fields, title and slug. To give pages a body or a summary, extend the type in config/schema/ (Types); engine-dmo describe type page lists the fields a type has.

Replace the starter layoutCopy Anchor Link

templates/_shared/base.html is a placeholder that writes its own <title> and canonical link, so check warns that it has no head(). Replace its head with head(), which writes the title, description, canonical link, hreflang links, robots and social tags from the page and the site’s SEO settings:

<!doctype html>
<html lang="{{ locale.code }}" dir="{{ locale.direction }}">
<head>
  <meta charset="utf-8">
  <meta name="viewport" content="width=device-width, initial-scale=1">
  {{ head() }}
</head>
<body>
  <main id="main">{% block body %}{% endblock %}</main>
</body>
</html>

SEO and structured data covers what head() prints.

Put it in a databaseCopy Anchor Link

cd my-site
export DATABASE_URL='postgres://meridian:meridian@localhost:5432/meridian?sslmode=disable'

engine-dmo check --no-db

engine-dmo migrate up

engine-dmo schema apply

engine-dmo seed apply

engine-dmo dev up

Sign in to the adminCopy Anchor Link

The admin is at /studio on any of the project’s sites. Staff users are created from the command line:

engine-dmo user create --email you@example.org --name "Your Name"

first user: added to the administrators group
created you@example.org (...) in groups administrators
enrolment link, valid 24 hours, single use:
  http://localhost:8080/studio/enrol/...

The first user created goes into administrators, which the starter’s grants.yaml gives the owner role. Later users name their groups with --group (repeatable). The link is built from server.base_url.

Open the link, choose a password of at least 12 characters, scan the code into an authenticator app and enter a code from it. The admin then shows your recovery codes once. Staff accounts require a second factor by default.

user create needs the migrations applied. It does not send mail: it prints the link.

Development shortcutsCopy Anchor Link

Two settings make signing in quicker on your own machine. Neither is allowed in production.

# seed/users/admin.yaml. Development only: seed apply skips users in production.
email: admin@example.test
name: Dev Admin
groups: [administrators]
password: correct horse battery staple
totp_secret: JBSWY3DPEHPK3PXP

What to do nextCopy Anchor Link

• Add a type, a field or a route with the engine-dmo dev verbs while dev up runs: The development loop.
• Learn what each file is for: Project layout.
• Model your content: Content modelling.
• Write templates: Templates.
• Point your coding agent at AGENTS.md and the two skills init wrote; the engine-dmo dev verbs regenerate them whenever they change the configuration.