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)

    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)

    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.