Quickstart

Use this page to choose the first setup path. Both distributions share the same Instagram and Google setup concepts, but they host callbacks and backend state differently.

Pick your path

Self-host Nudgra OSS

Run TanStack Start, Better Auth, Hono, Drizzle, pg-boss, and Postgres. Use this when you want to own the app server and database.

Run Nudgra Cloud

Run the Next.js dashboard with Convex Cloud. Use this when you want Convex to own backend state, auth, scheduling, and webhook functions.

Local prerequisites

Install these before either local setup path:

Git.
Node.js 24 or newer.
A Google account for sign-in.
A Meta Developer account.
An Instagram professional account.

Nudgra OSS also needs Docker or another Postgres database. Nudgra Cloud also needs a Convex account.

Fast local setup

Nudgra OSS
Nudgra Cloud

Clone and install

git clone https://github.com/MaikoCode/nudgra-oss nudgra-oss
cd nudgra-oss
npm install
cp .env.example .env

In Windows PowerShell:

git clone https://github.com/MaikoCode/nudgra-oss nudgra-oss
cd nudgra-oss
npm install
Copy-Item .env.example .env

Start Postgres

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

Configure the local environment

Set the local app URLs, generated secrets, and your operator email 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

Run the app

npm run db:migrate
npm run dev

Open http://localhost:3000.

Clone and install

git clone https://github.com/MaikoCode/nudgra-cloud nudgra-cloud
cd nudgra-cloud
npm install
cp .env.example .env.local

In Windows PowerShell:

git clone https://github.com/MaikoCode/nudgra-cloud nudgra-cloud
cd nudgra-cloud
npm install
Copy-Item .env.example .env.local

Configure the local environment

Set the local app URL and your allowed Google email in .env.local.

SITE_URL=http://localhost:3000
NUDGRA_ALLOWED_EMAILS=your-google-email@gmail.com

Add Google OAuth values

Create Google OAuth credentials, then set them in .env.local or in your Convex dev deployment.

AUTH_GOOGLE_ID=your-google-client-id
AUTH_GOOGLE_SECRET=your-google-client-secret

Run the app

npm run dev

Open http://localhost:3000.

Next steps

Set up Google OAuth.
Set up Meta / Instagram login and webhooks.
Deploy Nudgra OSS on a VPS or Nudgra Cloud on Vercel and Convex.

Start here

Shared setup

Pick your path

Self-host Nudgra OSS

Run Nudgra Cloud

Local prerequisites

Fast local setup

Next steps

​Pick your path

Self-host Nudgra OSS

Run Nudgra Cloud

​Local prerequisites

​Fast local setup

​Next steps

Pick your path

Local prerequisites

Fast local setup

Next steps