---
title: Running the platform
description: Day-to-day commands for the local development environment - prerequisites, database scripts, apps, and quality gates.
---

This page is the operating manual for a local development environment. Everything below runs from the repository root unless stated otherwise.

### Prerequisites

- **Node** 22.12 or newer (the repo targets modern toolchains).
- **pnpm** 11.20.0 (pinned via `packageManager`). Never npm.
- **A local Postgres** instance, and a `DATABASE_URL` that points at it (see [Configuration](/platform/configuration)).
- **Portless** handles local hostnames (`web.africaos`, `admin.africaos`) for the apps.

### One-time setup

```bash
pnpm install
cp .env.example .env      # then edit DATABASE_URL and any other values
pnpm db:migrate
pnpm db:seed              # development seed: users, orgs, registry, roles
pnpm db:register-apps     # register app.config.ts entries into platform.applications
pnpm db:seed:admin        # create the admin console credentials
```

`db:seed:admin` prints the admin name and password it creates - sign in to the [admin console](/platform/admin) with them.

### Running everything

```bash
pnpm dev                  # nx run-many -t dev: every app with a dev target
```

Or run apps individually:

| App | Command |
| --- | --- |
| Web (main host) | `pnpm --filter @africaos/web dev` (served at `web.africaos`) |
| Admin console | `pnpm --filter @africaos/admin dev` (served at `admin.africaos`) |
| Any single app | `pnpm nx run <project>:dev` |

### Database scripts

| Command | What it does |
| --- | --- |
| `pnpm db:migrate` | Applies pending migrations (idempotent). |
| `pnpm db:seed` | Development seed; re-runnable. |
| `pnpm db:seed:production` | Production baseline seed. |
| `pnpm db:register-apps` | Upserts all `app.config.ts` entries into the registry. |
| `pnpm db:seed:admin` | Creates/updates the admin account. |
| `pnpm db:verify:org` | Inspects an organization's state (dev helper). |

### Quality gates

Run these before pushing or opening a PR:

```bash
pnpm typecheck
pnpm test
pnpm lint
pnpm format
```

All four are Nx-aware - they run across every package that has the target, in dependency order. Scoped variants:

```bash
pnpm nx affected -t typecheck test lint
pnpm nx run @africaos/retail:test
pnpm --filter @africaos/web typecheck
```

### Common scenarios

**Adding or editing an application config.** Run `pnpm db:register-apps` after changing `app.config.ts` - the launcher and access gates read the registry.

**Changing the schema.** Add a migration (see [Migrations](/database/migrations)) and run `pnpm db:migrate`. Re-run `pnpm db:seed` if the new table needs seed data.

**The admin console does not list an organization.** The organization must be `verified` (the app shows active organizations). See the [lifecycle](/architecture/multi-tenancy).

**A new application does not appear in the launcher.** Check three things: it is registered (`pnpm db:register-apps`), it is enabled for the organization (`platform.organization_applications`), and the member holds `platform.applications.access`.

### Ports and hostnames

- Web app: `web.africaos` (portless maps the local hostname).
- Admin console: `admin.africaos`.
- The knowledgebase itself runs with `pnpm --filter knowledgebase dev` (see its package scripts).