Skip to content

Update README #1019

New issue

Have a question about this project? Sign up for a free GitHub account to open an issue and contact its maintainers and the community.

Sign up for GitHub

By clicking “Sign up for GitHub”, you agree to our terms of service and privacy statement. We’ll occasionally send you account related emails.

Already on GitHub? Sign in to your account

Merged
elie222 merged 2 commits into from
Nov 26, 2025
Merged

Update README #1019

Show file tree
Hide file tree
Changes from all commits
Commits
Show all changes
2 commits
Select commit Hold shift + click to select a range
2eb0b0f
update readme
elie222 Nov 26, 2025
7a09f4a
fix anchor links
elie222 Nov 26, 2025
File filter

Filter by extension

Filter by extension
Conversations
Failed to load comments.
Loading
Jump to
Jump to file
Failed to load files.
Loading
Diff view
Diff view
202 changes: 60 additions & 142 deletions README.md
View file
Open in desktop
Original file line number Diff line number Diff line change
Expand Up @@ -97,66 +97,41 @@ See our **[Self-Hosting Guide](docs/hosting/self-hosting.md)** for complete inst

#### Quick Start

1. **Start the database and Redis (recommended):**
1. **Start PostgreSQL and Redis:**
```bash
docker compose -f docker-compose.dev.yml up -d
```
This starts Postgres and Redis in Docker containers. Alternatively, you can use your own Postgres/Redis instances.

2. **Install dependencies and set up the database:**
2. **Install dependencies and set up environment:**
```bash
pnpm install
./docker/scripts/setup-env.sh # Creates .env with auto-generated secrets
```

3. **Configure OAuth and LLM:**

Edit `apps/web/.env` and add:
- **OAuth credentials** (at least one required): [Google OAuth](#google-oauth-setup) or [Microsoft OAuth](#microsoft-oauth-setup)
- **LLM provider**: Uncomment one provider block and add your API key

4. **Run database migrations:**
```bash
cd apps/web
cp .env.example .env
# Edit .env with your configuration
pnpm prisma migrate dev
```

3. **Run the development server:**
5. **Run the development server:**
```bash
pnpm dev
```

The app will be available at `http://localhost:3000`.

#### Detailed Setup

Make sure you have the above installed before starting.

The external services that are required are (detailed setup instructions below):

- [Google OAuth](https://console.cloud.google.com/apis/credentials)
- [Google PubSub](https://console.cloud.google.com/cloudpubsub/topic/list)

### Updating .env file: secrets

If you haven't already, create your `.env` file: `cp apps/web/.env.example apps/web/.env`

You can see a list of required variables in: `apps/web/env.ts`.

For a comprehensive reference of all environment variables, see the [Environment Variables Guide](docs/hosting/environment-variables.md).

The required environment variables:

- `AUTH_SECRET` -- can be any random string (try using `openssl rand -hex 32` for a quick secure random string)
- `EMAIL_ENCRYPT_SECRET` -- Secret key for encrypting OAuth tokens (try using `openssl rand -hex 32` for a secure key)
- `EMAIL_ENCRYPT_SALT` -- Salt for encrypting OAuth tokens (try using `openssl rand -hex 16` for a secure salt)


- `NEXT_PUBLIC_BASE_URL` -- The URL where your app is hosted (e.g., `http://localhost:3000` for local development or `https://yourdomain.com` for production).
- `INTERNAL_API_KEY` -- A secret key for internal API calls (try using `openssl rand -hex 32` for a secure key)

- `UPSTASH_REDIS_URL` -- Redis URL from Upstash. (can be empty if you are using Docker Compose)
- `UPSTASH_REDIS_TOKEN` -- Redis token from Upstash. (or specify your own random string if you are using Docker Compose)

- `NEXT_PUBLIC_BYPASS_PREMIUM_CHECKS` -- Set to `true` (default) to bypass all premium checks for self-hosting.
The setup script auto-generates all required secrets. The sections below cover the services you need to configure manually. For a comprehensive reference of all environment variables, see the [Environment Variables Guide](docs/hosting/environment-variables.md).

### Updating .env file with Google OAuth credentials:
### Google OAuth Setup

- `GOOGLE_CLIENT_ID` -- Google OAuth client ID. More info [here](https://next-auth.js.org/providers/google)
- `GOOGLE_CLIENT_SECRET` -- Google OAuth client secret. More info [here](https://next-auth.js.org/providers/google)

Go to [Google Cloud](https://console.cloud.google.com/). Create a new project if necessary.
Go to [Google Cloud Console](https://console.cloud.google.com/) and create a new project if necessary.

Create [new credentials](https://console.cloud.google.com/apis/credentials):

Expand Down Expand Up @@ -208,12 +183,34 @@ Create [new credentials](https://console.cloud.google.com/apis/credentials):
- [Google People API](https://console.cloud.google.com/marketplace/product/google/people.googleapis.com) (required)
- [Google Calendar API](https://console.cloud.google.com/marketplace/product/google/calendar-json.googleapis.com) (only required for calendar integration)

### Updating .env file with Microsoft OAuth credentials:
### Google PubSub Setup

PubSub enables real-time email notifications. Follow the [official guide](https://developers.google.com/gmail/api/guides/push):

1. [Create a topic](https://developers.google.com/gmail/api/guides/push#create_a_topic)
2. [Create a subscription](https://developers.google.com/gmail/api/guides/push#create_a_subscription)
3. [Grant publish rights on your topic](https://developers.google.com/gmail/api/guides/push#grant_publish_rights_on_your_topic)

Set `GOOGLE_PUBSUB_TOPIC_NAME` in your `.env` file.

When creating the subscription, select **Push** and set the URL to:
`https://yourdomain.com/api/google/webhook?token=TOKEN`

Set `GOOGLE_PUBSUB_VERIFICATION_TOKEN` in your `.env` file to the value of `TOKEN`.

**For local development**, use ngrok to expose your local server:

```sh
ngrok http 3000
```

Then update the webhook endpoint in the [Google PubSub subscriptions dashboard](https://console.cloud.google.com/cloudpubsub/subscription/list).

**Email watch renewal:** Gmail watch subscriptions expire periodically and must be renewed. If using Docker Compose, this is handled automatically by the cron container every 6 hours. Otherwise, set up a cron job to call `/api/watch/all` (see [Self-Hosting Guide](docs/hosting/self-hosting.md#scheduled-tasks)).

- `MICROSOFT_CLIENT_ID` -- Microsoft OAuth client ID
- `MICROSOFT_CLIENT_SECRET` -- Microsoft OAuth client secret
### Microsoft OAuth Setup

Go to [Microsoft Azure Portal](https://portal.azure.com/). Create a new Azure Active Directory app registration:
Go to [Microsoft Azure Portal](https://portal.azure.com/) and create a new Azure Active Directory app registration:

1. Navigate to Azure Active Directory
2. Go to "App registrations" in the left sidebar or search it in the searchbar
Expand All @@ -232,13 +229,12 @@ Go to [Microsoft Azure Portal](https://portal.azure.com/). Create a new Azure Ac

4. Get your credentials from the `Overview` tab:

1. The "Application (client) ID" value is your `MICROSOFT_CLIENT_ID`
2. To get your client secret:
- Click "Certificates & secrets" in the left sidebar
1. Copy the "Application (client) ID" → this is your `MICROSOFT_CLIENT_ID`
2. Go to "Certificates & secrets" in the left sidebar
- Click "New client secret"
- Add a description and choose an expiry
- Click "Add"
- Copy the `Value` - this is your `MICROSOFT_CLIENT_SECRET`. **Important:** copy `Value` and not `Secret ID`!
- Copy the `Value` → this is your `MICROSOFT_CLIENT_SECRET` (**Important:** copy `Value`, not `Secret ID`)

5. Configure API permissions:

Expand All @@ -262,15 +258,15 @@ Go to [Microsoft Azure Portal](https://portal.azure.com/). Create a new Azure Ac
6. Click "Add permissions"
7. Click "Grant admin consent" if you're an admin

6. Update your .env file with the credentials:
```plaintext
6. Update your `.env` file with the credentials:
```
MICROSOFT_CLIENT_ID=your_client_id_here
MICROSOFT_CLIENT_SECRET=your_client_secret_here
```
Comment on lines +262 to 265
Copy link
Copy Markdown
Contributor

@coderabbitai coderabbitai bot Nov 26, 2025

Choose a reason for hiding this comment

The reason will be displayed to describe this comment to others. Learn more.

⚠️ Potential issue | 🟡 Minor

Specify language identifier for fenced code block.

Per markdownlint, fenced code blocks should declare a language for syntax highlighting and semantic clarity. This block contains bash environment variable assignments.

-   ```
+   ```bash
    MICROSOFT_CLIENT_ID=your_client_id_here
    MICROSOFT_CLIENT_SECRET=your_client_secret_here
-   ```
+   ```
🧰 Tools
🪛 markdownlint-cli2 (0.18.1)

262-262: Fenced code blocks should have a language specified

(MD040, fenced-code-language)

🤖 Prompt for AI Agents 
In README.md around lines 262 to 265, the fenced code block showing environment
variables lacks a language identifier; update the opening fence to specify a
language (e.g., ```bash) so the block becomes a bash-marked fenced code block
for proper syntax highlighting and lint compliance.


### Updating .env file with LLM parameters
### LLM Setup

You need to configure an LLM provider. Supported options:
In your `.env` file, uncomment one of the LLM provider blocks and add your API key:

- [Anthropic](https://console.anthropic.com/settings/keys)
- [OpenAI](https://platform.openai.com/api-keys)
Expand All @@ -280,105 +276,27 @@ You need to configure an LLM provider. Supported options:
- [AWS Bedrock](https://aws.amazon.com/bedrock/)
- [Groq](https://console.groq.com/)

You can select the model you wish to use in the app on the `/settings` page.

### Running the app

Follow the [Quick Start](#quick-start) above, or run these commands:

```bash
docker compose -f docker-compose.dev.yml up -d # Start Postgres and Redis
pnpm prisma migrate dev # Run migrations
pnpm dev # Start the dev server
```

Alternatively, you can use remote services like [Upstash Redis](https://upstash.com/) or [Neon Postgres](https://neon.tech/) instead of Docker.

### Production Build with Docker
Users can also change the model in the app on the `/settings` page.

To build and run the full stack (App + DB + Redis) locally in production mode using Docker:
### Local Production Build

```bash
# Build and start all services (includes Postgres and Redis)
NEXT_PUBLIC_BASE_URL=http://localhost:3000 docker compose --profile all up --build
```

For production deployments with external databases, see the [Self-Hosting Guide](docs/hosting/self-hosting.md).

To run without Docker (local production build):
To test a production build locally:

```bash
# Without Docker
pnpm run build
pnpm start
```

Open [http://localhost:3000](http://localhost:3000) to view the app in your browser.

### Premium

Many features are available only to premium users. To upgrade yourself, make yourself an admin in the `.env`: `ADMINS=hello@gmail.com`
Then upgrade yourself at: [http://localhost:3000/admin](http://localhost:3000/admin).

### Set up push notifications via Google PubSub to handle emails in real time

Follow instructions [here](https://developers.google.com/gmail/api/guides/push).

1. [Create a topic](https://developers.google.com/gmail/api/guides/push#create_a_topic)
2. [Create a subscription](https://developers.google.com/gmail/api/guides/push#create_a_subscription)
3. [Grant publish rights on your topic](https://developers.google.com/gmail/api/guides/push#grant_publish_rights_on_your_topic)

Set env var `GOOGLE_PUBSUB_TOPIC_NAME`.
When creating the subscription select Push and the url should look something like: `https://www.getinboxzero.com/api/google/webhook?token=TOKEN` or `https://abc.ngrok-free.app/api/google/webhook?token=TOKEN` where the domain is your domain. Set `GOOGLE_PUBSUB_VERIFICATION_TOKEN` in your `.env` file to be the value of `TOKEN`.

To run in development ngrok can be helpful:

```sh
ngrok http 3000
# or with an ngrok domain to keep your endpoint stable (set `XYZ`):
ngrok http --domain=XYZ.ngrok-free.app 3000
```

And then update the webhook endpoint in the [Google PubSub subscriptions dashboard](https://console.cloud.google.com/cloudpubsub/subscription/list).

To start watching emails visit: `/api/watch/all`

### Watching for email updates

Set a cron job to run these:
The Google watch is necessary. Others are optional.

```json
"crons": [
{
"path": "/api/watch/all",
"schedule": "0 1 * * *"
},
{
"path": "/api/resend/summary/all",
"schedule": "0 16 * * 1"
},
{
"path": "/api/reply-tracker/disable-unused-auto-draft",
"schedule": "0 3 * * *"
}
]
# With Docker (includes Postgres and Redis)
NEXT_PUBLIC_BASE_URL=http://localhost:3000 docker compose --profile all up --build
```

[Here](https://vercel.com/guides/how-to-setup-cron-jobs-on-vercel#alternative-cron-providers) are some easy ways to run cron jobs. Upstash is a free, easy option. I could never get the Vercel `vercel.json`. Open to PRs if you find a fix for that.

### Advanced Docker Usage

For detailed instructions on:
- Building custom Docker images
- Using external databases (RDS, Neon, Upstash)
- AWS EC2 deployment with ALB
- AWS Copilot deployment (ECS/Fargate)
- Production configuration
### Self-Hosting

See our comprehensive guides:
For production deployments, see our guides:
- [Self-Hosting Guide](docs/hosting/self-hosting.md)
- [AWS EC2 Deployment Guide](docs/hosting/ec2-deployment.md)
- [AWS Copilot Deployment Guide](docs/hosting/aws-copilot.md)
- [AWS EC2 Deployment](docs/hosting/ec2-deployment.md)
- [AWS Copilot (ECS/Fargate)](docs/hosting/aws-copilot.md)


## Contributing to the project
Expand Down
8 changes: 4 additions & 4 deletions docs/hosting/environment-variables.md
View file
Open in desktop
Original file line number Diff line number Diff line change
Expand Up @@ -93,10 +93,10 @@ cp apps/web/.env.example apps/web/.env

For detailed setup instructions:

- **Google OAuth**: See [README - Google OAuth Setup](../../README.md#updating-env-file-with-google-oauth-credentials)
- **Microsoft OAuth**: See [README - Microsoft OAuth Setup](../../README.md#updating-env-file-with-microsoft-oauth-credentials)
- **Google PubSub**: See [README - PubSub Setup](../../README.md#set-up-push-notifications-via-google-pubsub-to-handle-emails-in-real-time)
- **LLM Configuration**: See [README - LLM Setup](../../README.md#updating-env-file-with-llm-parameters)
- **Google OAuth**: See [README - Google OAuth Setup](../../README.md#google-oauth-setup)
- **Microsoft OAuth**: See [README - Microsoft OAuth Setup](../../README.md#microsoft-oauth-setup)
- **Google PubSub**: See [README - PubSub Setup](../../README.md#google-pubsub-setup)
- **LLM Configuration**: See [README - LLM Setup](../../README.md#llm-setup)

## Notes

Expand Down
2 changes: 1 addition & 1 deletion version.txt
View file
Open in desktop
Original file line number Diff line number Diff line change
@@ -1 +1 @@
v2.20.29
v2.20.30
Loading