Setup

Required tools

Bun: curl -fsSL https://bun.com/install | bash

Docker: brew install --cask docker-desktop

Other tools: brew install opentofu kubectl kubectl-cnpg kubecm helm k9s fga openfga/tap/fga

Terraform

Make sure nothing is running on port 80, 443, 5432, or 6443.

bun tofu:init
bun tofu:apply

Login to ArgoCD with username admin and password admin.

(To destroy the cluster, run bun tofu:nuke.)

Prepare the platform database

bun --cwd packages/platform db:reset

This updates your packages/platform/.env file, creates the platform database, and inserts one row into the environment table.

Note: If drizzle-kit is stuck after outputting Reading config file, run bun run clean && bun install and try again.

Start the platform web app

bun --cwd packages/platform dev

Sign in using [email protected]. Hint: the six-digit verification code is printed in the terminal.

This also serves an /environment endpoint which tells ArgoCD to create a CNPG cluster corresponding to the row inserted, which has one database (the "environment database").

Resetting the environment database and OpenFGA

The core-schema reset does two things:

• Resets/recreates the environment database and applies the schema, then seeds it.
• Resets the OpenFGA store and writes the authorization model, updating packages/core-schema/.env.

1. Ensure the OpenFGA API is reachable on localhost:8080. Use k9s to port-forward the openfga service in the environment namespace

2. Run the reset:

bun --cwd packages/core-schema db:reset
 

Troubleshooting:
- If you see “Cannot reach FGA server” from `scripts/fga-reset.sh`, make sure the port-forward is active.
- Validate connectivity:
```bash
fga store list

## Connect the app template or an app to the environment database

For the app template, create and edit `apps/core/app-template/.env` with reference to `.env.example`.

For some app, e.g., `education/registration`:

- Edit `apps/education/registration/.env` with reference to `.env.example`.
- You will also need to change the appropriate line in `pg-rest.ts` to:

const pgRestUrl = 'http://postgrest.voltade-main.127.0.0.1.nip.io';

## Start the app template or an app

```bash
# For the app template:
bun --cwd apps/core/app-template dev

# For an app:
bun --cwd apps/education/registration dev

If your development server is not starting, run bun run clean:all && bun install from the root of the repository before continuing to troubleshoot.

Install an app in the platform web app

First, log in using the email [email protected]. Hint: The six-digit verification code is printed in the terminal where the platform web app is running.

bun voltade login

Then, install the app by referencing the directory of the app, for example:

bun voltade app:install apps/education/registration

The app should appear in the platform web app.

Miscellaneous Notes

Installation of PostgreSQL extensions

read

• Add source compiling to docker/postgres/Dockerfile: For most extensions that is not shipped with Postgres.

• Add to shared_preload_libraries in the cnpg-cluster.yaml: If it requires being loaded at startup, such as pg_stat_statements, supabase_vault.

• Add to the postInitApplicationSQL in the cnpg-cluster.yaml: If the installation requires superuser privileges, AND it introduces new objects (functions, tables, etc.) that need to be granted access to the platform_admin user. such as supabase_vault.

• Add to the extensions section in the cnpg-database.yaml: If it requires superuser to be installed, such as plv8, pgcrypto.

• Add it to extensions directory and link it to the current.sql: If it's pure SQL that doesn't require superuser privileges, such as nanoid.