Getting started

Set up Africa OS on your machine - prerequisites, install, environment configuration, database setup, and running the apps.

This page gets you from a clean machine to a running platform. The goal is a local instance where you can sign in, create an organization, and explore the retail application module end to end.

Prerequisites

Before you clone the repository, make sure your machine has:

Node.js 22.12 or newer - Africa OS runs on the current Node LTS. Blume, the docs tool, requires 22.12+.
pnpm 11.20.0 - the package manager is pinned in package.json (packageManager: "pnpm@11.20.0"). Use corepack enable to have pnpm install itself, or install it globally.
PostgreSQL 16+ - the platform requires a reachable Postgres instance. A local install, Docker container, or managed database all work.
Git - to clone the repository.

node --version   # 22.12 or newer
pnpm --version   # 11.20.0
psql --version   # 16 or newer

Clone and install

git clone git@github.com:veikeAgency/africaos.git
cd africaos
pnpm install

The install pulls the entire monorepo: every app, platform package, and application module. It is a large install, so give it a moment. If the postinstall build step runs, that is expected.

Set up the toolchain (Nx and vite-plus)

Beyond pnpm, two more tools drive the everyday workflow, and both are installed with pnpm install (they live in the root devDependencies):

Nx orchestrates tasks across the monorepo. Root scripts like pnpm dev, pnpm build, pnpm test, and pnpm lint delegate to it. It understands the dependency graph, caches results, and runs only what changed.
vite-plus (invoked as vp) owns the per-package quality gates: linting, tests, and formatting. Every package’s lint, test, and typecheck scripts call vp, and formatting is vp fmt . from the root.

Confirm both resolve from the workspace binaries:

npx nx --version   # v23.x
npx vp --version   # v0.2.x

Both come from the root package.json, with shared tool versions pinned once in the dependency catalog:

{
  "packageManager": "pnpm@11.20.0",
  "devDependencies": {
    "nx": "^23.1.1",
    "vite-plus": "catalog:"
  }
}

Run the first quality gate to verify the toolchain is wired end to end:

pnpm typecheck

Configure your environment

The root .env.example defines every environment variable the platform reads. Copy it and fill in the values:

cp .env.example .env

The only variable required to boot the database and run migrations is DATABASE_URL. The auth server needs a secret and a base URL:

DATABASE_URL=postgres://postgres:postgres@localhost:5432/africaos
BETTER_AUTH_SECRET=<any-long-random-string>
BETTER_AUTH_URL=http://localhost:3000

Add Google OAuth credentials (a web client from the Google Cloud Console):

GOOGLE_CLIENT_ID=<client-id>
GOOGLE_CLIENT_SECRET=<client-secret>

Add WorkOS credentials for enterprise single sign-on:

WORKOS_API_KEY=<api-key>
WORKOS_CLIENT_ID=<client-id>
WORKOS_REDIRECT_URI=http://localhost:3000

The full variable reference lives in the Configuration page.

Set up the database

Africa OS keeps one Postgres schema and drives it with migrations. Two commands get you to a working database:

pnpm db:migrate
pnpm db:seed

db:migrate applies every SQL migration under infra/database/migrations in order.
db:seed upserts a deterministic development dataset: users, organizations across the lifecycle, the application registry, and roles. It is safe to run repeatedly.

If you changed the application registry or added an application module, register the apps explicitly:

pnpm db:register-apps

Run the platform

The root dev script starts every app that has a dev target, orchestrated by Nx:

pnpm dev

The two apps you care about most:

Web app

The unified shell that mounts every application module. Available at the URL portless prints for web.africaos.

Admin console

The operations console for managing organizations. Available at the URL portless prints for admin.africaos.

Each app resolves a friendly hostname through portless, for example web.africaos and admin.africaos. The first run prints the exact URLs. If you prefer to avoid hostname rewriting, you can run a single app directly with pnpm --filter @africaos/web dev.

Open the web app. With the development seed there are users available - check infra/database/seeds/development.sql for the seeded identities. Otherwise, sign up or use Google OAuth if configured.

Create an organization

An organization is a tenant. Onboarding creates one and makes you its owner.

Open an application

Navigate to your organization and mount the retail application. The retail module is the reference implementation you can explore and copy.

Workflow scripts at a glance

The root package.json exposes the everyday commands:

Command	What it does
`pnpm dev`	Start every app with a `dev` target via Nx.
`pnpm build`	Build every app with a `build` target via Nx.
`pnpm typecheck`	Type-check every package that has a `typecheck` target.
`pnpm test`	Run every package’s test suite.
`pnpm lint`	Lint every package.
`pnpm lint:fix`	Lint and auto-fix.
`pnpm format`	Format the repository with vite-plus.
`pnpm format:check`	Verify formatting without changing files.
`pnpm db:migrate`	Apply pending database migrations.
`pnpm db:seed`	Upsert the development seed dataset.
`pnpm db:register-apps`	Re-sync the application registry.

Next steps

Now that the platform is running, the best path forward depends on what you want to do:

Understand the architecture

Read how multi-tenancy, authentication, and permissions work before changing code.

Follow a guide

Jump straight into a recipe: add a feature to an application, or add a whole new application.