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

# Installation

> Complete guide to installing, configuring, and running Instance with PostgreSQL, Redis, NextAuth, storage, and background workers.

## Prerequisites

Before starting, verify that your machine has the following tools installed:

| Tool | Minimum Version | Installation Check | Download Link |
| :- | :- | :- | :- |
| **Node.js** | 18.18.0+ (20+ LTS recommended) | `node -v` | [nodejs.org](https://nodejs.org/) |
| **pnpm** | 8.0+ | `pnpm -v` | `npm install -g pnpm` |
| **Git** | Any modern version | `git --version` | [git-scm.com](https://git-scm.com/) |
| **PostgreSQL** | PostgreSQL 14+ | Local or Cloud | [Neon (Free Cloud Postgres)](https://neon.tech) |
| **Redis** | Redis 6.2+ | Local or Cloud | [Upstash (Free Cloud Redis)](https://upstash.com) |

***

## Step 1: Clone the Repository

Open your terminal (PowerShell on Windows, or Terminal on macOS/Linux) and clone the repository:

```bash theme={null}
git clone https://github.com/instance-inc/instance.git
cd instance
```

***

## Step 2: Install Monorepo Dependencies

Instance uses pnpm workspaces to coordinate dependencies across apps and shared packages. Run:

```bash theme={null}
pnpm install
```

This installs all packages for the Web dashboard, API server, background workers, and shared database packages.

***

## Step 3: Prepare Environment Configuration

Create your local `.env` configuration file from the comprehensive template:

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

*(On Windows PowerShell, run `Copy-Item .env.example .env`)*

***

## Step 4: Rapid Bootstrapping Setup (2 Minutes to Run)

To get the application running locally and sign into the dashboard immediately, configure these core connections in your `.env` file:

### 1. PostgreSQL Database

* **Cloud Option (Recommended & Fastest)**: Sign up at [neon.tech](https://neon.tech), create a new project named `instance`, and copy the pooled and direct connection strings into your `.env`:
  ```env theme={null}
  DATABASE_URL="postgresql://user:password@ep-pooler.region.neon.tech/neondb?sslmode=require"
  DIRECT_URL="postgresql://user:password@ep-direct.region.neon.tech/neondb?sslmode=require"
  ```
* **Local Option**: If you have PostgreSQL running locally:
  ```env theme={null}
  DATABASE_URL="postgresql://postgres:postgres@localhost:5432/instance?sslmode=disable"
  DIRECT_URL="postgresql://postgres:postgres@localhost:5432/instance?sslmode=disable"
  ```

### 2. Redis Cache and Queue

* **Cloud Option (Fastest)**: Create a free Redis instance on [upstash.com](https://upstash.com) and copy your connection URL:
  ```env theme={null}
  REDIS_URL="rediss://default:token@region.upstash.io:6379"
  ```
* **Local Option**: If you have local Redis running (`redis-server`):
  ```env theme={null}
  REDIS_URL="redis://localhost:6379"
  ```

### 3. Generate NextAuth Authentication Secret

Instance uses NextAuth to secure sessions and encrypt JWT tokens. You need a random 32-character secret. You can generate one in either of two ways:

* **Terminal**: Run `openssl rand -hex 32` in your command line (if you have OpenSSL or Git Bash installed).
* **Online Generator**: Visit [generate-secret.vercel.app/32](https://generate-secret.vercel.app/32) to generate a secure random 32-character hex secret instantly.

Paste the generated string into your `.env`:

```env theme={null}
NEXTAUTH_SECRET="your-generated-32-character-secret"
NEXTAUTH_URL="http://localhost:3000"
```

### 4. Configure Google OAuth Login

1. Open [Google Cloud Console](https://console.cloud.google.com).
2. Create a project and navigate to **APIs & Services -> Credentials**.
3. Click **Create Credentials -> OAuth client ID** (Application type: **Web application**).
4. Set Authorized JavaScript origins: `http://localhost:3000`.
5. Set Authorized redirect URIs: `http://localhost:3000/api/auth/callback/google`.
6. Copy the credentials into your `.env`:
   ```env theme={null}
   GOOGLE_CLIENT_ID="your-google-client-id"
   GOOGLE_CLIENT_SECRET="your-google-client-secret"
   ```

***

## Step 5: Initialize the Database Schema

Generate the Prisma Client types and synchronize all tables with your PostgreSQL database:

```bash theme={null}
pnpm db:generate
pnpm db:push
```

***

## Step 6: Start the Development Stack

Launch all services concurrently:

```bash theme={null}
pnpm dev
```

Or run individual services in separate terminal tabs:

* **Web Dashboard**: `pnpm dev:web` (port 3000)
* **API Server**: `pnpm dev:api` (port 4000)
* **Background Workers**: `pnpm dev:workers`

Open your browser to `http://localhost:3000` and sign in. You are now running the Instance workspace!

***

## Step 7: Complete Feature Integrations (The Full Solution)

Once the core app is running, configure the remaining functional services in `.env` to unlock the full platform capabilities:

### 1. Meta and Instagram Credentials (Most Important)

This is the core foundation of Instance. To receive comments, story interactions, and direct messages in real time, you must connect your Meta Developer App and Instagram Professional account:

* Follow the complete step-by-step [Instagram Setup](file:///c:/Users/Sumama/Desktop/instance-oss/docs/instagram-setup.mdx) guide to obtain your `INSTAGRAM_APP_ID`, `INSTAGRAM_APP_SECRET`, and `META_WEBHOOK_VERIFY_TOKEN`.
* Configure the webhook endpoint and tunnel to start receiving live incoming customer events.

### 2. Cloudflare R2 Media Storage (S3-Compatible)

Used for storing voice notes, carousel images, and media attachments sent through DM automations:

1. Log in to [Cloudflare Dashboard](https://dash.cloudflare.com) and navigate to **R2 Object Storage**.
2. Click **Create bucket** (name it `instance-media`).
3. Click **Manage R2 API Tokens -> Create API Token** with Object Read and Write permissions.
4. In your bucket settings under **Public Access**, enable the Public `r2.dev` URL or connect a custom domain.
5. Add the keys to `.env`:
   ```env theme={null}
   R2_ACCOUNT_ID="your_cloudflare_account_id"
   R2_ACCESS_KEY_ID="your_r2_access_key_id"
   R2_SECRET_ACCESS_KEY="your_r2_secret_access_key"
   R2_BUCKET_NAME="instance-media"
   R2_PUBLIC_URL="https://pub-xxxxxx.r2.dev"
   ```

### 3. Email Setup (Passwordless Magic Links and Notifications)

Configure SMTP to send passwordless login links and system alert emails:

* **Using Gmail**: Create an App Password at [myaccount.google.com/apppasswords](https://myaccount.google.com/apppasswords). Copy your 16-character app password into `EMAIL_SERVER_PASSWORD`.
* **Using Transactional Email (Resend, SendGrid, Amazon SES, Postmark)**:
  ```env theme={null}
  EMAIL_SERVER_HOST="smtp.gmail.com"
  EMAIL_SERVER_PORT=587
  EMAIL_SERVER_USER="your-email@gmail.com"
  EMAIL_SERVER_PASSWORD="your-16-char-app-password"
  EMAIL_FROM="noreply@yourdomain.com"
  ```

### 4. Background Cron Security

Instance runs periodic background crons (such as hourly rate limit quota resets and paused account health checks). Generate a dedicated authorization key:

* **Terminal**: Run `openssl rand -hex 32` in your command line.
* **Online Generator**: Visit [generate-secret.vercel.app/32](https://generate-secret.vercel.app/32) to generate a random 32-character hex key.

Set your key in `.env`:

```env theme={null}
CRON_SECRET="your-generated-32-character-secret"
```

### 5. Meta Instagram Rate Limits and Pacing Controls

Instance includes built-in token-bucket rate limits and thread pacing matching official Meta specifications. The defaults in `.env.example` are pre-tuned for safety, and you can expand them as your Meta app tier increases:

```env theme={null}
# Outbound messages per second (Meta default: 100, expand up to 300)
META_SEND_RATE_LIMIT_PER_SEC=100

# Audio/video messages per second (Meta strictly caps at 10)
META_MEDIA_RATE_LIMIT_PER_SEC=10

# Comment-to-DM private replies per hour (Meta strictly caps at 750)
META_PRIVATE_REPLY_RATE_LIMIT_PER_HOUR=750

# Minimum human delay interval between messages sent to the same user (in seconds)
META_THREAD_PACING_MIN_INTERVAL_SEC=1.0

# Public comment replies per hour under posts (anti-spam safety limit)
META_COMMENT_REPLY_RATE_LIMIT_PER_HOUR=60

# Conversations API calls per second (Meta strictly caps at 2)
META_CONVERSATION_RATE_LIMIT_PER_SEC=2
```

***

## Common Troubleshooting

* **Prisma Client Generation Fails**: Run `pnpm postinstall` to rebuild shared monorepo packages.
* **Port In Use (3000, 4000, or 6379)**: Check if other processes are occupying these ports before starting dev servers.
* **Worker Jobs Not Executing**: Ensure Redis is running and reachable via the `REDIS_URL` in `.env`.


This documentation is built and hosted on [Mintlify](https://mintlify.com), a developer documentation platform.