216 lines
5.0 KiB
Plaintext
216 lines
5.0 KiB
Plaintext
---
|
||
title: Local Development
|
||
description: "A guide on how to run useSend’s codebase locally"
|
||
icon: code
|
||
---
|
||
|
||
## Introduction
|
||
|
||
useSend's codebase is fully [open-source on github](https://github.com/usesend/usesend)
|
||
|
||
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 useSend
|
||
|
||
- `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 useSend 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 useSend locally
|
||
|
||
To run useSend 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
|
||
|
||
<Steps>
|
||
<Step title="Fork the repo">
|
||
Click on the fork button on [GitHub](https://github.com/usesend/usesend) to fork the repo
|
||
</Step>
|
||
<Step title="Clone the repo">
|
||
Once the repo is forked you can clone it on your local machine using:
|
||
|
||
```bash
|
||
git clone https://github.com/your-username/usesend.git
|
||
```
|
||
|
||
</Step>
|
||
</Steps>
|
||
|
||
## Install Dependencies
|
||
|
||
<Steps>
|
||
<Step>
|
||
```bash
|
||
corepack enable
|
||
```
|
||
</Step>
|
||
|
||
<Step>
|
||
```bash
|
||
pnpm install
|
||
```
|
||
</Step>
|
||
</Steps>
|
||
|
||
## Setup environment variables:
|
||
|
||
<Steps>
|
||
<Step title="Copy the env.example file into .env">
|
||
```bash
|
||
cp .env.example .env
|
||
```
|
||
</Step>
|
||
<Step title="Nextauth secret">
|
||
Use the following command to generate a key and add it under ```NEXTAUTH_SECRET```
|
||
|
||
```bash
|
||
openssl rand -base64 32
|
||
```
|
||
|
||
</Step>
|
||
<Step title="Setup GitHub Oauth (optional)">
|
||
<Note>
|
||
You don't need this setup if you have `FROM_EMAIL` set in your environment
|
||
variables. for development email link will logged in the console.
|
||
</Note>
|
||
|
||
Next, [create a new GitHub App](https://github.com/settings/applications/new). This will allow you to sign in to useSend with your GitHub account.
|
||
|
||
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`
|
||
|
||
</Step>
|
||
<Step title="Setup AWS credentials (Optional)">
|
||
|
||
<Note>
|
||
You don't need this setup if you are using the local-sen-sns image. But email
|
||
will not be sent out.
|
||
</Note>
|
||
|
||
Next, we need to add in the [AWS credentials](https://docs.usesend.com/get-started/create-aws-credentials). Follow the detailed guide to get the AWS credentials with accurate permissions and add them in:
|
||
|
||
```
|
||
AWS_ACCESS_KEY=<access-key-id>
|
||
AWS_SECRET_KEY=<secret-access-key>
|
||
```
|
||
|
||
</Step>
|
||
</Steps>
|
||
|
||
## Running useSend 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
|
||
|
||
<Steps>
|
||
<Step title="Start the dashboard">
|
||
```bash
|
||
pnpm d
|
||
```
|
||
</Step>
|
||
<Step title="Dashboard and Landing page will start running">
|
||
Dashboard will be started on
|
||
```bash
|
||
http://localhost:3000
|
||
```
|
||
Landing page will be started on
|
||
|
||
```bash
|
||
http://localhost:3001
|
||
```
|
||
|
||
</Step>
|
||
<Step title="Once you login with GitHub you will be prompted with SES settings. You will need to run cloudflare tunnel to add the callback URL">
|
||
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
|
||
|
||
</Step>
|
||
</Steps>
|
||
|
||
### Option 2: Using your own database or hosted database
|
||
|
||
<Steps>
|
||
<Step title="Set up your PostgreSQL and Redis database in Environment Variables">
|
||
```bash
|
||
DATABASE_URL=""
|
||
REDIS_URL=""
|
||
```
|
||
</Step>
|
||
<Step title="Migrate the database">
|
||
```bash
|
||
pnpm db:migrate-dev
|
||
```
|
||
</Step>
|
||
<Step title="Start the development server">
|
||
```bash
|
||
pnpm dev
|
||
```
|
||
</Step>
|
||
<Step title="Once you login with GitHub you will be prompted with SES settings. You will need to run cloudflare tunnel to add the callback URL">
|
||
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
|
||
|
||
</Step>
|
||
</Steps>
|
||
|
||
## Run documentation
|
||
|
||
To run the documentation run the following command:
|
||
|
||
```bash
|
||
pnpm dev:docs
|
||
```
|