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

# Quickstart

> Pick a Nudgra setup path and get to a running local app.

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

<Columns cols={2}>
  <Card title="Self-host Nudgra OSS" icon="server" href="/oss/local-development">
    Run TanStack Start, Better Auth, Hono, Drizzle, pg-boss, and Postgres. Use this when you want to own the app server and database.
  </Card>

  <Card title="Run Nudgra Cloud" icon="cloud" href="/cloud/local-development">
    Run the Next.js dashboard with Convex Cloud. Use this when you want Convex to own backend state, auth, scheduling, and webhook functions.
  </Card>
</Columns>

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

<Tabs>
  <Tab title="Nudgra OSS">
    <Steps>
      <Step title="Clone and install">
        ```bash theme={null}
        git clone https://github.com/MaikoCode/nudgra-oss nudgra-oss
        cd nudgra-oss
        npm install
        cp .env.example .env
        ```

        In Windows PowerShell:

        ```powershell theme={null}
        git clone https://github.com/MaikoCode/nudgra-oss nudgra-oss
        cd nudgra-oss
        npm install
        Copy-Item .env.example .env
        ```
      </Step>

      <Step title="Start Postgres">
        ```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
        ```
      </Step>

      <Step title="Configure the local environment">
        Set the local app URLs, generated secrets, and your operator email 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
        ```
      </Step>

      <Step title="Run the app">
        ```bash theme={null}
        npm run db:migrate
        npm run dev
        ```

        Open `http://localhost:3000`.
      </Step>
    </Steps>
  </Tab>

  <Tab title="Nudgra Cloud">
    <Steps>
      <Step title="Clone and install">
        ```bash theme={null}
        git clone https://github.com/MaikoCode/nudgra-cloud nudgra-cloud
        cd nudgra-cloud
        npm install
        cp .env.example .env.local
        ```

        In Windows PowerShell:

        ```powershell theme={null}
        git clone https://github.com/MaikoCode/nudgra-cloud nudgra-cloud
        cd nudgra-cloud
        npm install
        Copy-Item .env.example .env.local
        ```
      </Step>

      <Step title="Configure the local environment">
        Set the local app URL and your allowed Google email in `.env.local`.

        ```env theme={null}
        SITE_URL=http://localhost:3000
        NUDGRA_ALLOWED_EMAILS=your-google-email@gmail.com
        ```
      </Step>

      <Step title="Add Google OAuth values">
        Create Google OAuth credentials, then set them in `.env.local` or in your Convex dev deployment.

        ```env theme={null}
        AUTH_GOOGLE_ID=your-google-client-id
        AUTH_GOOGLE_SECRET=your-google-client-secret
        ```
      </Step>

      <Step title="Run the app">
        ```bash theme={null}
        npm run dev
        ```

        Open `http://localhost:3000`.
      </Step>
    </Steps>
  </Tab>
</Tabs>

## Next steps

* Set up [Google OAuth](/shared/google-oauth).
* Set up [Meta / Instagram login and webhooks](/shared/meta-instagram-setup).
* Deploy [Nudgra OSS on a VPS](/oss/deploy-vps) or [Nudgra Cloud on Vercel and Convex](/cloud/deploy-vercel-convex).