--- title: Getting started description: 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. ```bash node --version # 22.12 or newer pnpm --version # 11.20.0 psql --version # 16 or newer ``` :::warning Use `pnpm` for everything in this project. Never use `npm`. The repository's lockfile and catalog are pnpm-based, and mixing package managers will corrupt the dependency tree. ::: ### Clone and install ```bash 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: ```bash 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: ```json { "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: ```bash pnpm typecheck ``` :::note Nx configuration lives in `nx.json` at the root; vite-plus pulls its defaults from the catalog in `pnpm-workspace.yaml`. See [Nx and pnpm](/tooling/nx-and-pnpm) and [vite-plus](/tooling/vite-plus) for how they behave. ::: ### Configure your environment The root `.env.example` defines every environment variable the platform reads. Copy it and fill in the values: ```bash cp .env.example .env ``` **Minimum (local development)** The only variable required to boot the database and run migrations is `DATABASE_URL`. The auth server needs a secret and a base URL: ```env DATABASE_URL=postgres://postgres:postgres@localhost:5432/africaos BETTER_AUTH_SECRET= BETTER_AUTH_URL=http://localhost:3000 ``` **With Google sign-in** Add Google OAuth credentials (a web client from the Google Cloud Console): ```env GOOGLE_CLIENT_ID= GOOGLE_CLIENT_SECRET= ``` **With WorkOS SSO** Add WorkOS credentials for enterprise single sign-on: ```env WORKOS_API_KEY= WORKOS_CLIENT_ID= WORKOS_REDIRECT_URI=http://localhost:3000 ``` The full variable reference lives in the [Configuration](/platform/configuration) page. :::info Environment variables are validated at startup by `@africaos/config` (`packages/config/env.config.ts`) using Effect and Zod. A missing or malformed variable fails fast with a clear message before anything boots. ::: ### Set up the database Africa OS keeps one Postgres schema and drives it with migrations. Two commands get you to a working database: ```bash 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: ```bash pnpm db:register-apps ``` ### Run the platform The root `dev` script starts every app that has a `dev` target, orchestrated by Nx: ```bash pnpm dev ``` The two apps you care about most: The unified shell that mounts every application module. Available at the URL portless prints for `web.africaos`. 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`. 1. **Sign in** 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. 2. **Create an organization** An organization is a tenant. Onboarding creates one and makes you its owner. 3. **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: Read how multi-tenancy, authentication, and permissions work before changing code. Jump straight into a recipe: add a feature to an application, or add a whole new application.