Pular para o conteúdo principal

Guia de instalação (detalhado)

O README resume o mínimo. Este guia cobre dependências, BDs, SMTP e problemas frequentes.

1. Pré-requisitos​

FerramentaVersão
Node.js20+ (Alpine 20 na imagem Docker)
npmo que vier com o Node 20
PostgreSQL14+ recomendado (duas bases ou dois schemas em hosts distintos)
Redis6+ (opcional em local; produção deve definir REDIS_*)
Git2.x
Docker / Composeopcional, para subir a API empacotada

Contas SMTP só se for testar reset de senha ou e-mail de boas-vindas.

2. Clonar e dependências​

git clone https://github.com/Gevtech/ARKUS_BACKEND.git
cd ARKUS_BACKEND
git checkout Develop
cp .env.example .env
npm install

O Nest carrega, por ordem: /app/.ENV, .ENV, .env, .env.local, .env.dev.

3. Preencher o ambiente​

Edite .env — nunca commite este ficheiro.

Mínimo para a API arrancar e autenticar:

  • JWT_SECRET — string longa aleatória
  • POSTGRES_HOST, POSTGRES_PORT, POSTGRES_USER, POSTGRES_PASSWORD, POSTGRES_DATABASE
  • AUTH_DATABASE_HOST, AUTH_DATABASE_PORT, AUTH_DATABASE_USER, AUTH_DATABASE_PASSWORD, AUTH_DATABASE_NAME

Se a tabela company não estiver em public:

DATABASE_SEARCH_PATH=cronospay,public

SSL remoto:

DATABASE_SSL=true
AUTH_DATABASE_SSL=true

CORS do front local (Vite em 5173, por exemplo):

CORS_ORIGIN=http://localhost:5173,http://localhost:3001

Lista completa e comentada: .env.example. Comportamento no container: operacao/env-container.md.

4. Schema SQL​

TypeORM não cria tabelas. Aplique os scripts relevantes na BD certa:

  1. Principal: docs/sql/company-table.sql, company-directory-tables.sql, e o que faltar em todastabelas.sql.
  2. Auth: docs/sql/auth_user_table.sql, seeds de templates (seed_global_email_template_*.sql), migrations em docs/sql/migrations/.

Ordem das migrations: 001 … 007 conforme o estado da BD.

5. Subir a API​

npm run start:dev

Esperado no log: Servidor a escutar em http://localhost:3000/api.

Validar:

curl -s http://localhost:3000/api/health
curl -s http://localhost:3000/api

Login:

curl -s -X POST http://localhost:3000/api/v1/auth/login \
  -H "Content-Type: application/json" \
  -d "{\"email\":\"maria@exemplo.pt\",\"password\":\"senhaSegura8\"}"

Swagger: http://localhost:3000/api/docs
Postman: docs/postman/CentralCRM_API.postman_collection.json + ambiente local.

6. Docker Compose​

Na raiz, com .ENV preenchido:

docker compose --env-file .ENV up -d --build

Healthcheck bate em GET /api/health. Se o Postgres for remoto, POSTGRES_HOST=localhost dentro do container está errado — use o IP/hostname acessível da rede do Compose. Diagnóstico: operacao/docker-db-debug.md.

Após mudar código: docker compose build --no-cache backend (a imagem copia dist/ no build).

7. Documentação MkDocs (opcional)​

python -m venv .venv-docs
# Windows: .venv-docs\Scripts\activate
# Unix: source .venv-docs/bin/activate
pip install -r requirements-docs.txt
mkdocs serve

Abra http://127.0.0.1:8000. Ver DOCS_SITE.md.

8. Problemas frequentes​

SintomaCausa típica
Processo sai no bootstrapSem host de BD nem defaults embutidos
ECONNREFUSED 127.0.0.1:5432 no DockerVariáveis POSTGRES_* / AUTH_DATABASE_* não chegaram ao container
401 em tudoJWT_SECRET diferente do emissor (default-crm) ou token expirado (JWT_EXPIRES_IN_SECONDS)
400 “inclua tenantId”JWT sem claim e sem x-tenant-id
CORS no browserDefinir CORS_ORIGIN com o origin exacto do front
Reset não envia e-mailSMTP_* em falta; a app pode usar fallbacks de desenvolvimento — não use isso em produção
Porta 3000 ocupadaO bootstrap tenta a seguinte porta e avisa no log

9. Próximo passo​