Setup e comandos de desenvolvimento

TLDR: O ambiente roda em container, orquestrado por targets de make que vêm do commons. make setup.bootstrap na primeira vez, make start no dia a dia.

Pré-requisitos

  • O COMMONS_DIR precisa estar exportado no shell — é o ~/.zshrc da máquina, configurado pelo setup do WeHive, que exporta. Sem ele o Makefile aborta com erro explícito. Se estiver faltando, recarregue o shell (exec zsh); em máquina nova, rode o setup do WeHive primeiro.
  • Docker em execução.
  • Credenciais e .env — ver o guia de credenciais.

Passos

Primeira vez

bash make setup.bootstrap

Dia a dia

Comando O que faz
make start sobe o ambiente de desenvolvimento (usa Overmind)
make stop derruba o ambiente
make console abre o console do Rails
make shell abre um shell no container
make clear limpa o ambiente (remove containers, volumes e networks)

Testes

Comando O que faz
make test roda a suíte completa
make test test=<caminho> roda um teste ou arquivo específico
make container.server.test.watch modo watch
make container.server.test.diff roda só os testes afetados pelo diff

Qualidade de código

Comando O que faz
make container.server.lint lint
make container.server.lint.fix lint com correção automática
make container.server.audit auditoria de segurança
make container.server.audit.security.dependencies auditoria de dependências

Banco de dados

Comando O que faz
make container.server.db.migrate roda as migrations
make container.server.db.rollback desfaz a última migration
make container.server.db.reset recria o banco
make container.server.db.seed popula o banco
make container.server.db.create / .drop / .prepare cria / apaga / prepara o banco

Credenciais

Comando O que faz
make container.server.edit-credentials edita as credenciais do ambiente atual
make container.server.edit-credentials.development ambiente de desenvolvimento
make container.server.edit-credentials.test ambiente de teste
make container.server.edit-credentials.production produção

Serviços do compose

O compose.yml monta os serviços compartilhados do commons — app, worker, migrations, seed — mais o mailcatcher. As dependências entre eles ficam em .project/docker/compose/dependencies.yml. Ver a spec da migração de server para app.

Os scripts que cada serviço executa vivem em run/ (run/server, run/worker, run/migrate, run/seed, run/test, run/lint, run/audit).

Provedores externos

Provedor Uso
Postmark envio de e-mail
AWS S3 armazenamento de arquivos (certificados, imagens)
Apolo (IBFT) autenticação dos membros e integração de cursos
trg-club recebe a notificação de vencimento de filiação — ver R-005

Troubleshooting

  • COMMONS_DIR is not set — o Makefile para antes de qualquer target. Recarregue o shell com exec zsh ou source ~/.zshrc.
  • Jobs em background — o GoodJob persiste no Postgres e expõe o painel em /good_job, acessível apenas para usuário admin. Job com falha fica visível e re-executável ali.
  • E-mail em desenvolvimento — o mailcatcher intercepta as mensagens; nada sai para fora.