diff --git a/README.md b/README.md index 8e28611f97..b8dd3f317a 100644 --- a/README.md +++ b/README.md @@ -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): @@ -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 @@ -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: @@ -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 ``` -### 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) @@ -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 diff --git a/docs/hosting/environment-variables.md b/docs/hosting/environment-variables.md index f1b8b4c803..fb0ec5c70b 100644 --- a/docs/hosting/environment-variables.md +++ b/docs/hosting/environment-variables.md @@ -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 diff --git a/version.txt b/version.txt index 674f71074b..d2e3e44741 100644 --- a/version.txt +++ b/version.txt @@ -1 +1 @@ -v2.20.29 +v2.20.30