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

# Local Development

> A guide on how to run useSend’s codebase locally

## 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 theme={null}
    git clone https://github.com/your-username/usesend.git
    ```
  </Step>
</Steps>

## Install Dependencies

<Steps>
  <Step>
    ```bash theme={null}
    corepack enable
    ```
  </Step>

  <Step>
    ```bash theme={null}
    pnpm install
    ```
  </Step>
</Steps>

## Setup environment variables:

<Steps>
  <Step title="Copy the env.example file into .env">
    ```bash theme={null}
     cp .env.example .env
    ```
  </Step>

  <Step title="Nextauth secret">
    Use the following command to generate a key and add it under `NEXTAUTH_SECRET`

    ```bash theme={null}
    openssl rand -base64 32
    ```
  </Step>

  <Step title="Create symlink for Next.js">
    Create a symlink so that Next.js can access the root `.env` file:

    ```bash theme={null}
    ln -s ../../.env apps/web/.env
    ```
  </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 theme={null}
    pnpm d
    ```
  </Step>

  <Step title="Dashboard and Landing page will start running">
    Dashboard will be started on

    ```bash theme={null}
    http://localhost:3000
    ```

    Landing page will be started on

    ```bash theme={null}
    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 theme={null}
    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 theme={null}
    DATABASE_URL=""
    REDIS_URL=""
    ```
  </Step>

  <Step title="Migrate the database">
    ```bash theme={null}
    pnpm db:migrate-dev
    ```
  </Step>

  <Step title="Start the development server">
    ```bash theme={null}
    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 theme={null}
    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 theme={null}
pnpm dev:docs
```