Skip to main content
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

1

Clone the repository

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

Install packages

npm install
3

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