> ## Documentation Index
> Fetch the complete documentation index at: https://docs.nudgra.com/llms.txt
> Use this file to discover all available pages before exploring further.

# Local development

> Run Nudgra OSS locally with Node.js, Postgres, and Better Auth.

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

<Steps>
  <Step title="Clone the repository">
    ```bash theme={null}
    git clone https://github.com/MaikoCode/nudgra-oss nudgra-oss
    cd nudgra-oss
    ```
  </Step>

  <Step title="Install packages">
    ```bash theme={null}
    npm install
    ```
  </Step>

  <Step title="Create the environment file">
    ```bash theme={null}
    cp .env.example .env
    ```

    In Windows PowerShell:

    ```powershell theme={null}
    Copy-Item .env.example .env
    ```
  </Step>
</Steps>

## Start Postgres

If you use Docker, start a local Postgres container:

```bash theme={null}
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:

```powershell theme={null}
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`:

```env theme={null}
DATABASE_URL=postgres://nudgra:nudgra@localhost:5432/nudgra
DATABASE_SSL=false
```

## Configure local values

Set the minimum local values in `.env`:

```env theme={null}
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:

```bash theme={null}
openssl rand -base64 32
openssl rand -hex 32
```

Or generate them with Node:

```bash theme={null}
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](/shared/google-oauth), then set:

```env theme={null}
GOOGLE_CLIENT_ID=your-google-client-id
GOOGLE_CLIENT_SECRET=your-google-client-secret
```

For local Nudgra OSS, use:

```text theme={null}
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:

```bash theme={null}
npm run db:migrate
npm run dev
```

Open:

```text theme={null}
http://localhost:3000
```

## Useful commands

```bash theme={null}
npm run typecheck
npm run test
npm run test:visual
npm run db:studio
```