KM Koushik
04d0f4b123
* feat: support standard AWS env vars and default credential chain Replace non-standard AWS_ACCESS_KEY / AWS_SECRET_KEY with the AWS-standard AWS_ACCESS_KEY_ID / AWS_SECRET_ACCESS_KEY. The old names are kept as fallbacks in the runtimeEnv for backward compatibility. Both vars are now optional. When omitted, the credentials object is not passed to SESv2Client, STSClient, or SNSClient — the AWS SDK then falls back to its default provider chain (IAM roles, ECS task roles, instance profiles, etc.), which is the recommended approach for cloud-native deployments. Closes #316 Co-Authored-By: Claude Sonnet 4.6 <noreply@anthropic.com> * Potential fix for pull request finding Co-authored-by: Copilot Autofix powered by AI <175728472+Copilot@users.noreply.github.com> * refactor: extract shared getAwsCredentialOptions helper and add partial-config guard - Move the credential spread logic into a single credentials.ts helper so SESv2Client, STSClient, and SNSClient all share one implementation - Throw a clear error if only one of AWS_ACCESS_KEY_ID / AWS_SECRET_ACCESS_KEY is set, preventing silent fallback to the default provider chain with a half-configured environment Co-Authored-By: Claude Sonnet 4.6 <noreply@anthropic.com> * fix: align AWS env vars in docker and docs * fix: use alias import for AWS credentials helper --------- Co-authored-by: purva <purvahk08@gmail.com> Co-authored-by: Purva Kandalgaonkar <136103488+purva-8@users.noreply.github.com>
224 lines
5.2 KiB
Plaintext
224 lines
5.2 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="Create symlink for Next.js">
|
||
Create a symlink so that Next.js can access the root `.env` file:
|
||
|
||
```bash
|
||
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_ID=<access-key-id>
|
||
AWS_SECRET_ACCESS_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
|
||
```
|