Getting Started with Open Mercato

01Prepare your tools

Install Node.js 24.x and Docker with Compose. Start Docker Desktop if you use it. On Windows, run these commands in a WSL2 terminal with Docker integration enabled.

node --version
docker compose version
corepack enable

Node should report v24.x.x and Compose should print its version. corepack enable makes Yarn available; the project selects version 4.17.1.

02Create the application

Run these commands in the directory where you keep your projects. They create a new folder named mercato-demo.

npx create-mercato-app@0.7.0 \
  mercato-demo \
  --preset classic \
  --agents none \
  --no-init-git
cd mercato-demo
yarn --version

classic selects the standard modules. --agents none skips AI assistant configuration; --no-init-git skips Git repository initialization. If npm asks to download the package, answer y.

You are now inside the application directory. yarn --version should print 4.17.1. Run all remaining commands here.

03Start the database and services

Copy the local configuration and start the services from the included Compose file. PostgreSQL stores data, Redis supports caching and queues, and Meilisearch provides search.

cp .env.example .env
docker compose up -d
docker compose ps

In a new project, the settings in .env match these containers. The database connection is:

DATABASE_URL=postgres://postgres:postgres@localhost:5432/open-mercato

Wait until docker compose ps shows three running services and PostgreSQL is healthy. These settings include example passwords for development on your own computer.

04Start the application and sign in

yarn install
yarn setup

yarn install downloads dependencies. yarn setup generates application files, applies database migrations, creates initial data and starts the server. Leave this terminal running.

Open localhost:3000/backend. For this local setup, sign in with superadmin@acme.com and password secret. You should reach the application dashboard.

05Add your own page

Stop the server with Ctrl+C. In your editor, create the following three files and their directories. The hello module adds a simple page for signed-in users.

export const metadata = {
  name: 'hello',
  title: 'Hello',
  version: '0.1.0',
}

export const metadata = {
  requireAuth: true,
  pageTitle: 'Hello',
}

import { Page, PageHeader, PageBody } from '@open-mercato/ui/backend/Page'

export default function HelloPage() {
  return (
    <Page>
      <PageHeader title="Hello, Mercato" />
      <PageBody>
        <p>My first Open Mercato page.</p>
      </PageBody>
    </Page>
  )
}

In src/modules.ts, add this entry inside the enabledModules array, alongside the existing modules:

{ id: 'hello', from: '@app' },

Regenerate the module registry and restart the application:

yarn generate
yarn dev

Visit localhost:3000/backend/hello. You should see Hello, Mercato. Edit the paragraph in page.tsx and save to see your change in the browser.

06Resume work the next day

The next day, open a terminal in mercato-demo and run:

docker compose start
yarn dev

When you finish, stop the server with Ctrl+C and stop the services with the command below. Your data stays on disk. You can resume work without running yarn setup again.

docker compose stop