Run it locally

This guide takes you from a clean machine to a running Archetype instance on your laptop: the Django backend in Docker (driven by just), the Next.js frontend (in its dev container or with pnpm), a migrated database, populated search indexes, and a working admin login. Follow the steps in order — the path is designed to succeed on the first try.

The standard development split is backend in Docker + frontend in its own dev container; running the frontend on the host with pnpm is a supported alternative. You do not run Django or Celery directly; the just recipes wrap docker compose for you.

Prerequisites

Install these before you start:

Docker with the Compose plugin (docker compose version)
just — the command runner used for every backend recipe (brew install just, cargo install just, or a prebuilt binary). You can run the underlying docker compose commands directly if you prefer.
Node 26+ and pnpm 12 — only if you run the frontend on the host instead of its dev container. Install the pinned version with npm install -g [email protected]; pnpm 11 can’t switch itself to 12.
uv + Python 3.15 — only needed for host-side backend tooling (linting, the architecture check); the stack itself runs entirely in Docker. Use a current uv (uv self update): older releases can’t download Python 3.15.1.

1. Get the code

The backend and frontend are separate repositories. Clone both side by side; the docs call the backend checkout api/:

git clone https://github.com/archetype-pal/backend.git api
git clone https://github.com/archetype-pal/frontend.git frontend

2. Start the backend stack

From the backend checkout, create the environment file, then bring up Postgres, Meilisearch, Redis, SIPI (the IIIF image server), Celery, and the API:

cd api
cp config/test.env config/.env   # development defaults; the recipes refuse to run without it
just up-bg        # start detached; use `just up` to watch logs

This publishes the API on http://localhost:8000, Meilisearch on :7700, Postgres on :5432, Redis on :6379, and the SIPI image server on :8182 (bound to 127.0.0.1 only). Every recipe passes --env-file config/.env to docker compose; the copied defaults work as-is for local development. This stack runs under the Compose project name archetype-dev, so it never collides with a full archetype stack from the infrastructure repo on the same machine.

3. Run the database migrations

just migrate

4. Create the search indexes

Meilisearch starts empty. Create the index schemas, then load documents from the database:

just setup-search-indexes      # create indexes + settings (no documents)
just sync-all-search-indexes   # load documents from the DB

A fresh database has no records yet, so the indexes will be empty — that is expected. See Load your own corpus to import data.

5. Create an admin user

docker compose --env-file config/.env run --rm api python manage.py createsuperuser

(just bash followed by python manage.py createsuperuser does the same.)

Follow the prompts to set a username and password.

6. Start the frontend

In the frontend checkout, start the dev container. Its environment is set in compose.yml, already pointed at the backend above, so no .env is needed:

cd ../frontend
just up-bg        # dev server in Docker on :3000; `just up` runs it in the foreground

To run on the host instead, install dependencies, create your environment file, and start the dev server:

pnpm install
cp .env.example .env
pnpm dev

.env needs four variables. The .env.example API, IIIF and CORS defaults already match the backend above; NEXT_PUBLIC_SITE_URL is only used for metadata, sitemap and robots:

NEXT_PUBLIC_API_URL=http://localhost:8000       # no trailing slash
NEXT_PUBLIC_IIIF_UPSTREAM=http://localhost:8182
NEXT_PUBLIC_SITE_URL=https://archetype.example.org
CORS_ALLOWED_ORIGINS=http://localhost:3000,http://localhost:8000

The public site is now live at http://localhost:3000.

7. Log in

Open http://localhost:3000/login and sign in with the superuser you created in step 5. You now have a full local stack: public site, backoffice, API, image server, and search.

Where to go next

Working in the codebase — the layering rules, and the test and lint commands.
Contribution workflow — branching, commit style and the checks CI runs.
Load your own corpus — import manuscript images and records, then rebuild the search indexes.
Configuration — every backend and frontend environment variable.
Production deployment — the full stack behind nginx, from the infrastructure repository.
The API — the REST surface, with its schema at /api/v1/schema/ and Swagger UI at /api/v1/docs/.