> ## 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.

# Environment variables

> Configure Nudgra Cloud environment variables for local development, Vercel, and Convex.

Nudgra Cloud splits production configuration between the Next.js host and the Convex deployment.

## Local baseline

Copy `.env.example` to `.env.local`:

```bash theme={null}
cp .env.example .env.local
```

In Windows PowerShell:

```powershell theme={null}
Copy-Item .env.example .env.local
```

Local values usually look like this:

```env theme={null}
NEXT_PUBLIC_CONVEX_URL=
NEXT_PUBLIC_CONVEX_SITE_URL=

SITE_URL=http://localhost:3000
CONVEX_DEPLOY_KEY=

AUTH_GOOGLE_ID=
AUTH_GOOGLE_SECRET=
NUDGRA_ALLOWED_EMAILS=you@example.com

META_APP_ID=
META_APP_SECRET=
META_VERIFY_TOKEN=
```

`npx convex dev` writes `NEXT_PUBLIC_CONVEX_URL` and `NEXT_PUBLIC_CONVEX_SITE_URL` locally.

## Vercel variables

Set these on Vercel:

| Variable            | Purpose                                                                                       |
| ------------------- | --------------------------------------------------------------------------------------------- |
| `CONVEX_DEPLOY_KEY` | Lets `npx convex deploy --cmd "npm run build"` deploy the Convex backend during hosted builds |
| `SITE_URL`          | Public app origin used by Next.js routes, Meta OAuth callbacks, and tracked links             |
| `META_APP_ID`       | Meta app ID used by the Next.js connect route                                                 |
| `META_APP_SECRET`   | Meta app secret used by the Next.js Meta routes                                               |
| `META_VERIFY_TOKEN` | Verify-token presence check for the Meta connect flow                                         |

## Convex production variables

Set these on the Convex production deployment:

| Variable                | Purpose                                                                  |
| ----------------------- | ------------------------------------------------------------------------ |
| `AUTH_GOOGLE_ID`        | Google sign-in client ID                                                 |
| `AUTH_GOOGLE_SECRET`    | Google sign-in client secret                                             |
| `NUDGRA_ALLOWED_EMAILS` | Comma-separated Google emails allowed to access this private deployment  |
| `META_APP_ID`           | Meta app ID                                                              |
| `META_APP_SECRET`       | Meta app secret                                                          |
| `META_VERIFY_TOKEN`     | Meta webhook verification token                                          |
| `SITE_URL`              | Public app origin used by tracked links and callback-aware backend flows |
| `JWT_PRIVATE_KEY`       | Convex Auth signing key                                                  |
| `JWKS`                  | Convex Auth JWKS document                                                |

<Warning>
  `JWT_PRIVATE_KEY` and `JWKS` are required by Convex Auth. Generate them with `npx @convex-dev/auth --prod`; do not handcraft them unless you are following the Convex Auth manual setup docs.
</Warning>

## Required production shape

Keep `SITE_URL` exact in both Vercel and Convex:

```env theme={null}
SITE_URL=https://your-app-domain.com
```

Do not use a Vercel preview URL or localhost value in production.

Set the allowed Google emails:

```bash theme={null}
npx convex env set --prod NUDGRA_ALLOWED_EMAILS your-google-email@gmail.com
```

Set the public app origin:

```bash theme={null}
npx convex env set --prod SITE_URL https://your-app-domain.com
```

After Google and Meta are configured, set:

```bash theme={null}
npx convex env set --prod AUTH_GOOGLE_ID your-google-client-id
npx convex env set --prod AUTH_GOOGLE_SECRET your-google-client-secret
npx convex env set --prod META_APP_ID your-instagram-app-id
npx convex env set --prod META_APP_SECRET your-instagram-app-secret
npx convex env set --prod META_VERIFY_TOKEN your-random-verify-token
```

## Generate random tokens

Generate `META_VERIFY_TOKEN` with OpenSSL:

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

Or generate it with Node:

```bash theme={null}
node -e "console.log(require('crypto').randomBytes(32).toString('hex'))"
```

## Important secrets

Keep a private copy of these production secrets:

* `JWT_PRIVATE_KEY`.
* `JWKS`.
* `AUTH_GOOGLE_SECRET`.
* `META_APP_SECRET`.
* `META_VERIFY_TOKEN`.
* `CONVEX_DEPLOY_KEY`.