Skip to main content
Pré-requisitos:
  • Node.js v20 ou superior
  • npm v10+
  • Docker Desktop instalado e rodando
  • Git

​
1. Clonar o repositório

git clone <url-do-repositorio>
cd hub-marketplace-backend

​
2. Subir a infraestrutura local (Docker)

O projeto usa PostgreSQL 15 e Redis como dependências. O jeito mais rápido de tê-los rodando é via Docker Compose, cujo arquivo está na pasta docker/ na raiz do monorepo: 
# Da raiz do monorepo (pasta Fonte/)
docker compose -f docker/docker-compose.yml up -d
Isso sobe dois containers:
ContainerImagemPortaCredenciais padrão
hub_postgrespostgres:155432user: hub_user / pass: hub_pass / db: hub_db
hub_redisredis:latest6379sem senha (desenvolvimento local)
Para parar os containers sem apagar os dados: docker compose -f docker/docker-compose.yml stopPara apagar tudo (incluindo volumes): docker compose -f docker/docker-compose.yml down -v

​
3. Instalar dependências

npm install

​
4. Configurar variáveis de ambiente

Copie o arquivo de exemplo: 
cp .env.example .env
Edite o .env com os valores corretos para seu ambiente: 
# ─── Banco de dados ───────────────────────────────────────
DB_HOST=localhost
DB_PORT=5432
DB_USER=hub_user
DB_PASS=hub_pass
DB_NAME=hub_db

# ─── Aplicação ────────────────────────────────────────────
APP_PORT=3000

# ─── Redis ────────────────────────────────────────────────
REDIS_HOST=localhost
REDIS_PORT=6379
REDIS_PASSWORD=                  # Deixar vazio em desenvolvimento local

# ─── Segurança ────────────────────────────────────────────
JWT_SECRET=algum_segredo_forte_aqui
TOKEN_ENCRYPTION_KEY=chave_de_32_caracteres_aqui

# ─── Mercado Livre OAuth ───────────────────────────────────
MERCADO_LIVRE_API_URL=https://api.mercadolibre.com
ML_REDIRECT_URI=http://localhost:3000/integrations/mercadolivre/callback
ML_CLIENT_ID=
ML_CLIENT_SECRET=

# ─── CORS ─────────────────────────────────────────────────
FRONTEND_URL=http://localhost:3001

# ─── E-mail (Resend) ──────────────────────────────────────
RESEND_API_KEY=re_sua_chave_aqui
EMAIL_FROM=OmniDom <no-reply@send.domsoftware.com.br>
As variáveis JWT_SECRET e TOKEN_ENCRYPTION_KEY são críticas para segurança. Use valores aleatórios e longos. Nunca compartilhe os valores de produção.

​
Referência completa de variáveis

VariávelObrigatóriaDescrição
DB_HOST✅Host do PostgreSQL
DB_PORT✅Porta do PostgreSQL (padrão: 5432)
DB_USER✅Usuário do banco
DB_PASS✅Senha do banco
DB_NAME✅Nome do banco de dados
APP_PORT✅Porta em que a API vai escutar (padrão: 3000)
REDIS_HOST✅Host do Redis (filas BullMQ)
REDIS_PORT✅Porta do Redis (padrão: 6379)
REDIS_PASSWORDSenha do Redis (deixar vazio em dev local)
JWT_SECRET✅Segredo para assinar os JWT de acesso
TOKEN_ENCRYPTION_KEY✅Chave AES para criptografar tokens OAuth de terceiros
MERCADO_LIVRE_API_URL✅URL base da API do Mercado Livre
ML_REDIRECT_URI✅URI de callback OAuth do Mercado Livre
ML_CLIENT_IDApp ID do Mercado Livre (necessário para integração)
ML_CLIENT_SECRETApp Secret do Mercado Livre
FRONTEND_URL✅URL do frontend — usada na política de CORS
RESEND_API_KEYAPI key do Resend para envio de e-mails
EMAIL_FROMRemetente padrão dos e-mails transacionais

​
5. Executar as migrations

O banco começa vazio. As migrations criam todas as tabelas: 
npm run migration:run
As migrations lêem as variáveis do .env automaticamente via dotenv. Certifique-se de que o banco está acessível antes de rodar.

​
6. Rodar em desenvolvimento

npm run start:dev
A API estará disponível em http://localhost:3000 (ou na porta definida em APP_PORT). O servidor reinicia automaticamente ao detectar mudanças nos arquivos (modo --watch).

​
7. Verificar se está funcionando

Acesse a documentação Swagger gerada automaticamente: 
http://localhost:3000/api
Você verá todos os endpoints documentados e poderá testar chamadas direto pelo browser.

​
Comandos disponíveis

ComandoO que faz
npm run start:devDesenvolvimento com hot reload
npm run start:debugDesenvolvimento com debugger Node.js em modo watch
npm run buildCompila o TypeScript para dist/
npm run start:prodRoda o build compilado (produção)
npm run migration:generate -- --name=NomeDaAlteracaoGera migration a partir das entities
npm run migration:runExecuta migrations pendentes
npm run migration:revertReverte a última migration
npm run migration:showLista o status de todas as migrations
npm run testRoda testes unitários
npm run test:e2eRoda testes end-to-end
npm run test:covTestes com relatório de cobertura
npm run lintESLint com auto-fix
npm run formatPrettier em todos os arquivos src/
npm run emailPreview dos templates de e-mail (React Email)

​
Migrations

O projeto usa TypeORM com migrations para controle de esquema. O synchronize está desabilitado — nunca altere o banco sem criar uma migration.

​
Gerar uma migration após alterar uma entity

# Gera a migration automaticamente comparando entities com o banco
npm run migration:generate -- --name=AddSkuToProduct

# Revisa o arquivo gerado em src/database/migrations/
# Execute após revisar
npm run migration:run
Sempre revise o arquivo de migration gerado antes de executar. O TypeORM às vezes gera operações destrutivas (DROP COLUMN, DROP TABLE) que precisam ser verificadas.

​
Endpoints principais

MétodoRotaDescrição
POST/auth/loginLogin — retorna accessToken + cookie
POST/auth/refreshRenova o access token via cookie
POST/auth/logoutEncerra a sessão
GET/apiDocumentação Swagger
GET/catalog/productsLista produtos
GET/ordersLista pedidos
GET/integrationsLista integrações do tenant
GET/queue/adminDashboard do Bull Board (filas)

​
Troubleshooting

O PostgreSQL não está rodando. Execute:
docker compose -f docker/docker-compose.yml up -d postgres
Aguarde alguns segundos e tente novamente.
O Redis não está rodando. Execute:
docker compose -f docker/docker-compose.yml up -d redis
As migrations exigem o projeto compilado. O comando npm run migration:run faz o build automaticamente. Se o erro persistir, rode manualmente:
npm run build
npm run migration:run
Verifique a variável FRONTEND_URL no .env. Ela precisa ser exatamente a origem do frontend, incluindo protocolo e porta:
FRONTEND_URL=http://localhost:3001
O arquivo .env não foi encontrado. Certifique-se de que ele existe na raiz do backend (não na raiz do monorepo) e que o processo está sendo iniciado no diretório correto.
O Swagger só está disponível em modo de desenvolvimento. Se o build de produção estiver sendo usado, o endpoint /api não estará disponível.