From bc237c881c45a9c5ddfa8f66e1ab293d7d053bf9 Mon Sep 17 00:00:00 2001 From: Harsh Shrikant Bhat <90265455+harshsbhat@users.noreply.github.com> Date: Sat, 27 Jul 2024 03:17:10 +0530 Subject: [PATCH] feat: Added local development guide (#39) * Added local development guide * Added local development guide * Added local development guide * Update local.mdx --------- Co-authored-by: harshsbhat Co-authored-by: KM Koushik --- .env.example | 20 ++++ README.md | 8 +- apps/docs/get-started/local.mdx | 200 ++++++++++++++++++++++++++++++++ apps/docs/mint.json | 1 + 4 files changed, 223 insertions(+), 6 deletions(-) create mode 100644 .env.example create mode 100644 apps/docs/get-started/local.mdx diff --git a/.env.example b/.env.example new file mode 100644 index 0000000..49825a9 --- /dev/null +++ b/.env.example @@ -0,0 +1,20 @@ +DATABASE_URL="postgresql://unsend:password@localhost:54320/unsend" +REDIS_URL="redis://localhost:6379" + + + +NEXTAUTH_URL="http://localhost:3000" + +GITHUB_ID="" +GITHUB_SECRET="" + +AWS_DEFAULT_REGION="us-east-1" +AWS_SECRET_KEY="" +AWS_ACCESS_KEY="" + +NEXTAUTH_SECRET="" + + +API_RATE_LIMIT=2 + +NEXT_PUBLIC_IS_CLOUD=false \ No newline at end of file diff --git a/README.md b/README.md index cd59785..57211ce 100644 --- a/README.md +++ b/README.md @@ -70,13 +70,9 @@ We're currently working on opening unsend for public beta. ## Local Development -### Requirements +Follow our detailed guide to run Unsend locally -To run Unsend locally, you will need - -- Node.js (v18 or above) -- Postgres SQL Database -- Docker (optional) +[http://localhost:3002/get-started/local](http://localhost:3002/get-started/local) ## Docker diff --git a/apps/docs/get-started/local.mdx b/apps/docs/get-started/local.mdx new file mode 100644 index 0000000..a3c796b --- /dev/null +++ b/apps/docs/get-started/local.mdx @@ -0,0 +1,200 @@ +--- +title: Local Development +description: "A guide on how to run Unsend’s codebase locally" +icon: code +--- + +## Introduction + +Unsend's codebase is fully [open-source on github](https://github.com/unsend-dev/unsend) + +Here is the codebase structure + + ``` +apps + ├── docs + ├── marketing + ├── web +packages + ├── eslint-config + ├── sdk + ├── tailwind-config + ├── typescript-config + ├── ui + ``` + +The ```apps``` directory contains the code for: + +- ```web```: Code for our dashboard and email infra + +- ```marketing```: The code for the landing page of Unsend + +- ```docs```: The documentation that you are currently reading. + +The ```packages``` directory contains the code for: + +- ```eslint-config``` package contains shared ESLint configuration settings + +- ```sdk``` package contains typescript sdk for unsend rest api + +- ```tailwind-config``` This package contains a shared Tailwind CSS configuration. + +- ```typescript-config``` This package contains a shared typescript configuration + +- ```ui``` This package is a collection of reusable UI components like buttons, badges, etc + +## Running Unsend locally + +To run Unsend, locally you will need to setup the following: + +- [AWS](https://aws.amazon.com/) Free tier account will work. + +- [Cloudflare](https://www.cloudflare.com/) Free tier account will work. + +- [Docker](https://docs.docker.com/engine/install/) Recommended but not mandatory + +## Fork and Clone the repo + + + + Click on the fork button on [Github](https://github.com/unsend-dev/unsend) to fork the repo + + + Once the repo is forked you can clone it on your local machine using: + + ```bash + git clone https://github.com/your-username/unsend.git + ``` + + + +## Install Dependencies + + + +```bash +corepack enable +``` + + + +```bash +pnpm install +``` + + + +## Setup environment variables: + + + + ```bash + cp .env.example .env + ``` + + + Use the following command to generate a key and add it under ```NEXTAUTH_SECRET``` + + ```bash + openssl rand -base64 32 + ``` + + + + Next, [create a new GitHub App](https://github.com/settings/applications/new). This will allow you to sign in to Unsend with your GitHub account.4 + + Add the homepage as: + + ``` + http://localhost:3000/login + ``` + + and callback URL as: + ``` + http://localhost:3000/api/auth/callback/github + ``` + + Once the app is added you can add the Client ID under ``GITHUB_ID``and CLIENT SECRET under ```GITHUB_SECRET``` + + + + Next, we need to add in the [AWS credentials](https://docs.unsend.dev/get-started/create-aws-credentials). Follow the detailed guide to get the AWS credentials with accurate permissions and add them in: + + ``` + AWS_ACCESS_KEY_ID= + AWS_SECRET_ACCESS_KEY= + ``` + + Once the app is added you can add the Client ID under ``GITHUB_ID``and CLIENT SECRET under ```GITHUB_SECRET``` + + + +## Running Unsend locally +We are using a local Postgresql server and a local Redis server. But if you don't have docker you can also manually set these up. + +### Option 1: Using Docker Recommended + + +```bash +pnpm d +``` + + +Dashboard will be started on +```bash +http://localhost:3000 +``` +Landing page will be started on + +```bash +http://localhost:3001 +``` + + +Run the following command to get the URL. Here is the more detailed guide by [cloudflare](https://developers.cloudflare.com/pages/how-to/preview-with-cloudflare-tunnel/) +```bash +cloudflared tunnel --url http://localhost:3000 +``` + +You can paste the URL provided by cloudflare in the Callback URL section + + + + +### Option 2: Using your own database or hosted database + + +```bash +DATABASE_URL="" +REDIS_URL="" +``` + + +```bash +pnpm db:migrate-dev +``` + + +```bash +pnpm dev +``` + + +Run the following command to get the URL. Here is the more detailed guide by [cloudflare](https://developers.cloudflare.com/pages/how-to/preview-with-cloudflare-tunnel/) +```bash +cloudflared tunnel --url http://localhost:3000 +``` + +You can paste the URL provided by cloudflare in the Callback URL section + + + + + +## Run documentation + +To run the documentation run the following command: + +```bash +pnpm dev:docs +``` diff --git a/apps/docs/mint.json b/apps/docs/mint.json index 19ac85e..777ae5c 100644 --- a/apps/docs/mint.json +++ b/apps/docs/mint.json @@ -49,6 +49,7 @@ "pages": [ "introduction", "get-started/nodejs", + "get-started/local", "get-started/self-hosting" ] },