Local development

Local development is best for dashboard work and UI testing. Use a VPS or HTTPS tunnel when you need Meta to call webhook URLs from the public internet.

Prerequisites

Install:

Git.
Node.js 24 or newer.
Docker, unless you already have a local Postgres database.

Install dependencies

Clone the repository

git clone https://github.com/MaikoCode/nudgra-oss nudgra-oss
cd nudgra-oss

Install packages

npm install

Create the environment file

cp .env.example .env

In Windows PowerShell:

Copy-Item .env.example .env

Start Postgres

If you use Docker, start a local Postgres container:

docker run --name nudgra-postgres \
  -e POSTGRES_DB=nudgra \
  -e POSTGRES_USER=nudgra \
  -e POSTGRES_PASSWORD=nudgra \
  -p 5432:5432 \
  -d postgres:17-alpine

In Windows PowerShell:

docker run --name nudgra-postgres `
  -e POSTGRES_DB=nudgra `
  -e POSTGRES_USER=nudgra `
  -e POSTGRES_PASSWORD=nudgra `
  -p 5432:5432 `
  -d postgres:17-alpine

Keep these local database values in .env:

DATABASE_URL=postgres://nudgra:nudgra@localhost:5432/nudgra
DATABASE_SSL=false

Configure local values

Set the minimum local values in .env:

SITE_URL=http://localhost:3000
BETTER_AUTH_URL=http://localhost:3000
TRUSTED_ORIGINS=http://localhost:3000,http://127.0.0.1:3000
BETTER_AUTH_SECRET=your-generated-secret
TOKEN_ENCRYPTION_KEY=your-generated-token-secret
OPERATOR_EMAIL_ALLOWLIST=your-google-email@gmail.com

Generate secrets with OpenSSL:

openssl rand -base64 32
openssl rand -hex 32

Or generate them with Node:

node -e "console.log(require('crypto').randomBytes(32).toString('base64url'))"
node -e "console.log(require('crypto').randomBytes(32).toString('hex'))"

Configure Google OAuth

Google OAuth is required for normal sign-in. Follow Google OAuth, then set:

GOOGLE_CLIENT_ID=your-google-client-id
GOOGLE_CLIENT_SECRET=your-google-client-secret

For local Nudgra OSS, use:

Authorized JavaScript origin:
http://localhost:3000

Authorized redirect URI:
http://localhost:3000/api/auth/callback/google

Run the app

Run migrations, then start the app:

npm run db:migrate
npm run dev

Open:

http://localhost:3000

Useful commands

npm run typecheck
npm run test
npm run test:visual
npm run db:studio

​Prerequisites

​Install dependencies

​Start Postgres

​Configure local values

​Configure Google OAuth

​Run the app

​Useful commands