Madmail

Desenvolvimento local

Introdução

O Madmail é construído sobre um código aberto no GitHub. O repositório se chama usesend: é o nome do projeto open-source de origem, e é ele que você clona.

A estrutura é esta:

apps
├── docs
├── marketing
├── smtp-server
├── web
packages
├── analytics
├── email-editor
├── eslint-config
├── lib
├── python-sdk
├── sdk
├── typescript-config
├── ui

Em apps ficam:

  • web: o painel e a infraestrutura de envio;

  • marketing: o site institucional e a documentação que você está lendo agora;

  • smtp-server: o proxy SMTP;

  • docs: a documentação antiga, ainda no repositório.

Em packages ficam:

  • analytics: instrumentação e métricas;

  • email-editor: o editor de emails;

  • eslint-config: configuração de ESLint compartilhada;

  • lib: código compartilhado entre os apps;

  • python-sdk e sdk: os SDKs Python e TypeScript da API REST;

  • typescript-config: configuração de TypeScript compartilhada;

  • ui: componentes de interface reutilizáveis, como botões e badges.

O que você precisa

Para rodar o projeto localmente, tenha:

  • uma conta na AWS — a camada gratuita dá conta;

  • uma conta na Cloudflare — a camada gratuita dá conta;

  • Docker, recomendado mas não obrigatório.

Fazer o fork e clonar

1

Fazer o fork

Clique em fork no GitHub.

2

Clonar o repositório

Com o fork criado, clone na sua máquina:

git clone https://github.com/<seu-usuario>/usesend.git

Instalar as dependências

1
corepack enable
2
pnpm install

Configurar as variáveis de ambiente

1

Copiar o .env.example para .env

 cp .env.example .env
2

Segredo do NextAuth

Gere uma chave com o comando abaixo e coloque em NEXTAUTH_SECRET:

openssl rand -base64 32
3

Criar o symlink para o Next.js

Crie um symlink para o Next.js enxergar o .env da raiz:

ln -s ../../.env apps/web/.env
4

Configurar o OAuth do GitHub (opcional)

Nota

Você não precisa disso se tiver FROM_EMAIL nas variáveis de ambiente: em desenvolvimento, o link de login sai no console.

Depois, crie um GitHub App para conseguir entrar com a sua conta do GitHub.

Use como homepage:

http://localhost:3000/login

e como callback URL:

http://localhost:3000/api/auth/callback/github

Criado o app, coloque o Client ID em GITHUB_ID e o Client Secret em GITHUB_SECRET.

5

Configurar as credenciais AWS (opcional)

Nota

Você não precisa disso se estiver usando a imagem local-ses-sns. Mas nesse caso nenhum email sai de verdade.

Agora entram as credenciais AWS. Siga o guia detalhado para gerar as credenciais com as permissões certas e coloque em:

AWS_ACCESS_KEY_ID=<access-key-id>
AWS_SECRET_ACCESS_KEY=<secret-access-key>

Rodar na sua máquina

O setup usa um PostgreSQL e um Redis locais. Sem Docker, você pode subir os dois na mão.

Opção 1: com Docker (recomendado)

1

Subir o painel

pnpm d
2

O painel e o site sobem juntos

O painel sobe em

http://localhost:3000

O site institucional sobe em

http://localhost:3001
3

Depois do login pelo GitHub, o app pede a configuração do SES — para informar a callback URL você precisa de um túnel da Cloudflare

Rode o comando abaixo para obter a URL. O guia detalhado é este, da Cloudflare.

cloudflared tunnel --url http://localhost:3000

Cole a URL devolvida pela Cloudflare no campo de callback URL.

Opção 2: com um banco seu ou hospedado

1

Aponte o seu PostgreSQL e o seu Redis nas variáveis de ambiente

DATABASE_URL=""
REDIS_URL=""
2

Rodar as migrations

pnpm db:migrate-dev
3

Subir o servidor de desenvolvimento

pnpm dev
4

Depois do login pelo GitHub, o app pede a configuração do SES — para informar a callback URL você precisa de um túnel da Cloudflare

Rode o comando abaixo para obter a URL. O guia detalhado é este, da Cloudflare.

cloudflared tunnel --url http://localhost:3000

Cole a URL devolvida pela Cloudflare no campo de callback URL.

Rodar a documentação

A documentação faz parte do site institucional. Para subir só ela:

pnpm dev:marketing

Depois abra http://localhost:3001/docs.