Guia de Instalação e Configuração

Este guia detalha os passos para configurar e executar o backend da API Trace Point em seu ambiente de desenvolvimento, tanto com Docker quanto manualmente.

4. Requisitos de Ambiente

Antes de iniciar, certifique-se de que você possui os seguintes softwares instalados em sua máquina, dependendo do método de execução escolhido:

4.1. Com Docker (Método Recomendado):

4.2. Execução Manual:

5. Instalação e Configuração Detalhada

5.1. Clonagem do Repositório

Primeiramente, clone o repositório do projeto do GitHub para o seu ambiente local e navegue para o diretório criado:

git clone https://github.com/vyctor-carvalho/Trace_Point.git
cd Trace_Point

5.2. Rodando com Docker (Recomendado)

A utilização do Docker simplifica a configuração do ambiente, pois todos os serviços (aplicação e banco de dados) são executados em contêineres isolados.

Passo 1: Copie e Configure o Arquivo de Ambiente

O projeto utiliza um arquivo .env para configurar as variáveis de ambiente. Copie o arquivo de exemplo .env.copy para criar seu próprio arquivo .env:

cp .env.copy .env

Para a configuração padrão com Docker, o conteúdo do .env copiado de .env.copy geralmente já está otimizado e deve ser semelhante a este (verifique o seu .env.copy para os valores exatos):

# Configurações para Docker
SYSTEM_API_PORT=3000

# Dados do banco
DB_HOST=db
DB_USER=postgres
DB_PORT=sua_porta
DB_PASSWORD=postgres
DB_NAME=trace_point

# JWT
JWT_SECRET=sua_chave_secreta
REFRESH_SECRET=sua_chave
JWT_EXPIRES_IN=3600
REFRSH_TOKEN_EXPIRES_IN=604800

Passo 2: Suba os Contêineres

Com o Docker e Docker Compose instalados e o arquivo .env configurado, execute o seguinte comando na raiz do projeto para construir as imagens (se ainda não existirem) e iniciar os contêineres:

docker-compose up --build

5.3. Acesso via pgAdmin (com Docker)

Se o seu docker-compose.yml inclui o serviço do pgAdmin, você poderá acessá-lo. (Ex: http://localhost:8080, verifique a porta no seu docker-compose.yml).

Conecte-se ao banco de dados PostgreSQL (serviço db) com as credenciais definidas no seu .env (padrão: usuário postgres, senha postgres, host db, porta 5432).

5.4. Execução Manual (Sem Docker)

Se preferir não usar Docker, você pode configurar e rodar a aplicação diretamente na sua máquina.

Passo 1: Instale as Dependências

npm install

Passo 2: Configure o Arquivo de Ambiente (.env)

Copie .env.copy para .env e edite-o com as configurações para o seu ambiente local. Um exemplo completo seria:

# Configurações do servidor
SYSTEM_API_PORT=3001 # Defina a porta em que sua API local irá rodar

# Dados do banco de dados para execução manual
DB_HOST=localhost    # Ou o IP/host do seu servidor PostgreSQL local
DB_PORT=5432         # A porta em que seu PostgreSQL está escutando
DB_USER=seu_usuario_postgres  # Seu nome de usuário do PostgreSQL
DB_PASSWORD=sua_senha_postgres # A senha do seu usuário do PostgreSQL
DB_NAME=trace_point   # O nome do banco de dados que você criou para este projeto

# Configurações de JWT - JSON Web Token
JWT_SECRET=minhaChaveSecretaMuitoForteParaDesenvolvimento123!@#
REFRESH_SECRET=outraChaveSecretaMaisForteAindaParaRefreshTokenABC#$%
JWT_EXPIRES_IN=3600      
REFRSH_TOKEN_EXPIRES_IN=604800

Importante: Substitua os valores de exemplo pelos seus próprios valores seguros.

Passo 3: Rode as Migrações do Banco de Dados

Com o banco de dados PostgreSQL em execução e o .env configurado, aplique as migrações para criar as tabelas:

npm run migration:run
Clique para saber mais sobre os comandos de migração

As migrações do TypeORM são usadas para gerenciar e versionar o esquema do seu banco de dados de forma incremental. Cada migração representa uma alteração no banco (como criar uma tabela, adicionar uma coluna, etc.).

Configuramos alguns scripts NPM no seu package.json para facilitar o uso dos comandos de migração do TypeORM. Lembre-se que o script base typeorm (ou typeorm:cli) configura o DataSource para esses comandos, geralmente lendo as variáveis de ambiente `TYPEORM_*` ou o arquivo `AppDataSource.ts`.

  • npm run migration:create -- src/migrations/NomeDaSuaMigracao

    Cria um novo arquivo de migração em branco na pasta src/migrations/ com o nome fornecido (ex: CreateUsersTable). Você então edita este arquivo para adicionar seus comandos SQL (usando queryRunner.query("SEU SQL AQUI")) ou métodos do QueryBuilder do TypeORM nos métodos up (para aplicar) e down (para reverter).

    Exemplo para criar a seed do admin que discutimos:

    npm run migration:create -- src/migrations/CreateDefaultAdminUserSeed

    Depois, você editaria o arquivo ...-CreateDefaultAdminUserSeed.ts gerado.

  • npm run migration:generate -- src/migrations/NomeDaSuaMigracao

    Tenta gerar automaticamente os comandos SQL para uma nova migração com base nas mudanças que você fez nas suas entidades TypeORM (definidas em src/models/) desde a última migração. É crucial revisar cuidadosamente o arquivo gerado antes de aplicá-lo, pois a geração automática pode não cobrir todos os casos perfeitamente.

  • npm run migration:run

    Executa todas as migrações pendentes que ainda não foram aplicadas ao banco de dados. É o comando que você usa para atualizar seu banco para o estado mais recente definido pelas suas migrações.

  • npm run migration:revert

    Reverte a última migração que foi aplicada. Útil se você precisar desfazer a alteração mais recente no banco de dados que foi feita por uma migração.

Para que esses comandos funcionem corretamente, seu `AppDataSource.ts` deve estar configurado com os caminhos corretos para suas entidades e migrações, e as credenciais de banco de dados devem estar acessíveis (geralmente via variáveis de ambiente lidas pelo `AppDataSource.ts` ou pelas variáveis `TYPEORM_*` definidas no script npm).

Passo 4: Inicie o Servidor de Desenvolvimento (Após Migrações)

Finalmente, inicie a aplicação em modo de desenvolvimento:

npm run dev

O servidor deverá iniciar na porta que você especificou em `SYSTEM_API_PORT`.

{/* Mantenha o seu script aqui, por exemplo: ou */}