Guia de Configuração para Full-Stack com Angular, NestJS e PostgreSQL (Docker no WSL2)

Guia de Configuração para Desenvolvimento Full-Stack com Angular, NestJS e MySQL (Docker no WSL2)

Este guia detalha a configuração de um ambiente de desenvolvimento full-stack utilizando Angular (frontend), NestJS (backend) e PostgreSQL (banco de dados), tudo orquestrado com Docker Compose e otimizado para Windows com WSL2 e VS Code Dev Containers.

1. Pré-requisitos

Certifique-se de ter as seguintes ferramentas instaladas e configuradas no seu sistema:

Windows 10/11 (com WSL2 ativado): Essencial para o desempenho do Docker e Linux.
WSL2 - Uma distribuição Linux (ex: Ubuntu): Onde você clonará o projeto e executará os comandos Docker.
Docker Desktop for Windows: Integra o Docker ao WSL2, fornecendo o motor Docker.
Visual Studio Code (VS Code): Seu ambiente de desenvolvimento.
Extensão Remote - Containers para VS Code: Permite trabalhar dentro dos contêineres Docker.

2. Estrutura do Projeto

A estrutura de diretórios esperada é a seguinte:

raíz-do-projeto/ 
├── backend-nest/ 
│ ├── .devcontainer/ 
│ │ └── devcontainer.json 
│ ├── Dockerfile 
│ ├── package.json 
│ └── ... (código NestJS) 
├── frontend-angular/ 
│ ├── .devcontainer/ 
│ │ └── devcontainer.json 
│ ├── Dockerfile 
│ ├── package.json 
│ └── ... (código Angular) 
├── docker-compose.yml 
└── README.md (este arquivo)

3. Configurações dos Arquivos

3.1. docker-compose.yml

Este arquivo define os serviços (contêineres) da sua aplicação e como eles se relacionam.

version: '3.8'
services:
frontend:
  build:
    context: ./frontend-angular
    dockerfile: ./Dockerfile
  container_name: frontend-angular
  ports:
    - '4200:4200'
  volumes:
    - frontend_node_modules:/usr/src/app/node_modules
    - ./frontend-angular:/usr/src/app:delegated
  networks:
    - dev-net
  environment:
    - NODE_ENV=development
  working_dir: /usr/src/app

backend:
  build:
    context: ./backend-nest
    dockerfile: Dockerfile
  container_name: backend-nest
  ports:
    - "3000:3000"
    - "9229:9229"
  volumes:
    - backend_node_modules:/usr/src/app/node_modules
    - ./backend-nest:/usr/src/app
  environment:
    NODE_ENV: development
   # Formato: postgresql://USER:PASSWORD@HOST:PORT/DATABASE?schema=public
    DATABASE_URL: postgresql://user:password@postgres-db:5432/talentlink?schema=public
  depends_on:
    - postgres-db # Garante que o Postgres inicie antes do backend
  networks:
    - dev-net

# Serviço de Banco de Dados alterado para PostgreSQL
postgres-db:
  image: postgres:15-alpine # Usando uma imagem leve do Postgres 15
  container_name: talentlink_postgres
  ports:
    - "5432:5432" # Porta padrão do PostgreSQL
  environment:
    POSTGRES_USER: user
    POSTGRES_PASSWORD: password
    POSTGRES_DB: talentlink
    # Opcional: define o diretório de dados para garantir permissões corretas no Alpine
    PGDATA: /var/lib/postgresql/data/pgdata
  volumes:
    # Volume persistente apontando para o caminho correto do Postgres
    - postgres_data:/var/lib/postgresql/data
  networks:
    - dev-net

volumes:
frontend_node_modules:
backend_node_modules:
postgres_data: # Volume renomeado

networks:
dev-net:
  driver: bridge

3.2. frontend-angular/Dockerfile

#Define a imagem Docker para o serviço Angular.
FROM node:18-bookworm-slim
# Instala ferramentas de depuração (procps, net-tools, iproute2, lsof)
RUN apt-get update && \
  apt-get install -y --no-install-recommends \
      procps \
      net-tools \
      iproute2 \
      lsof \
  && rm -rf /var/lib/apt/lists/*
WORKDIR /usr/src/app
COPY package*.json ./
# Concede permissões ao diretório de trabalho para o usuário 'node'
RUN chown -R node:node /usr/src/app
USER node # Define o usuário padrão para 'node'

# Instala as dependências do projeto
RUN npm install

COPY . . # Copia o restante do código-fonte para o contêiner
EXPOSE 4200 # Informa ao Docker que o contêiner escuta na porta 4200

# Comando para iniciar o servidor de desenvolvimento Angular
CMD ["npm", "start"]

3.3. frontend-angular/package.json

Define os scripts npm para o frontend. O script start contém as flags necessárias para o servidor Angular funcionar corretamente no Docker.

{
"name": "frontend-angular",
"version": "0.0.0",
"scripts": {
  "ng": "ng",
  "start": "ng serve --host 0.0.0.0 --port 4200 --disable-host-check --watch true",
  "build": "ng build",
  "watch": "ng build --watch --configuration development",
  "test": "ng test"
},
"private": true,
"dependencies": {
  "@angular/animations": "^17.3.0",
  "@angular/common": "^17.3.0",
  "@angular/compiler": "^17.3.0",
  "@angular/core": "^17.3.0",
  "@angular/forms": "^17.3.0",
  "@angular/platform-browser": "^17.3.0",
  "@angular/platform-browser-dynamic": "^17.3.0",
  "@angular/router": "^17.3.0",
  "rxjs": "~7.8.0",
  "tslib": "^2.3.0",
  "zone.js": "~0.14.3"
},
"devDependencies": {
  "@angular-devkit/build-angular": "^17.3.0",
  "@angular/cli": "^17.3.0",
  "@angular/compiler-cli": "^17.3.0",
  "@types/jasmine": "~5.1.0",
  "@types/node": "^18.18.0",
  "jasmine-core": "~5.1.0",
  "karma": "~6.4.0",
  "karma-chrome-launcher": "~3.2.0",
  "karma-coverage": "~2.2.0",
  "karma-jasmine": "~5.1.0",
  "karma-jasmine-html-reporter": "~2.1.0",
  "typescript": "~5.4.2"
}
}

3.4. frontend-angular/.devcontainer/devcontainer.json

Configuração para o Visual Studio Code trabalhar dentro do contêiner do frontend.

JSON

{
"name": "Frontend Angular Dev",
"dockerComposeFile": "../../docker-compose.yml",
"service": "frontend",
"workspaceFolder": "/usr/src/app",
"updateRemoteUserUID": true, 
"remoteUser": "node",        
"containerUser": "node",     

"customizations": {
  "vscode": {
    "extensions": [
      "angular.ng-template",
      "dbaeumer.vscode-eslint",
      "esbenp.prettier-vscode",
      "ms-vscode.vscode-typescript-next"
    ],
    "settings": {
      "editor.formatOnSave": true,
      "editor.defaultFormatter": "esbenp.prettier-vscode"
    }
  }
},
"postCreateCommand": "npm install" 
}

3.5. backend-nest/Dockerfile

Define a imagem Docker para o serviço NestJS.

Dockerfile

FROM node:18-bookworm-slim
WORKDIR /usr/src/app
COPY package*.json ./
RUN chown -R node:node /usr/src/app
USER node
RUN npm install
COPY . .
EXPOSE 3000
CMD ["npm", "run", "start:dev"]

3.6. backend-nest/.devcontainer/devcontainer.json

Configuração para o Visual Studio Code trabalhar dentro do contêiner do backend.

{
"name": "Backend NestJS Dev",
"dockerComposeFile": "../../docker-compose.yml",
"service": "backend",
"workspaceFolder": "/usr/src/app",
"updateRemoteUserUID": true, 
"remoteUser": "node",        
"containerUser": "node",     

"customizations": {
  "vscode": {
    "extensions": [
      "dbaeumer.vscode-eslint",
      "esbenp.prettier-vscode"
    ],
    "settings": {
      "editor.formatOnSave": true,
      "editor.defaultFormatter": "esbenp.prettier-vscode"
    }
  }
},
"postCreateCommand": "npm install && npm run start:dev"
}

4. Resolução de Problemas e Mitigações

Os seguintes passos abordam os problemas comuns encontrados durante a configuração:

4.1. Limpeza Completa e Reset do Docker

Para garantir que não haja resquícios de builds anteriores ou volumes corrompidos:

Feche o VS Code.
No seu terminal WSL, na raiz do projeto (TalentLink/), execute:

docker compose down --volumes --rmi all
docker volume rm frontend_node_modules backend_node_modules postgres_data # Remova todos os volumes nomeados

No Docker Desktop (Windows), vá em Settings (engrenagem) -> Troubleshoot -> "Clean / Purge data" (ou "Reset to factory defaults"). Confirme e aguarde o processo.

4.2. Correção de Permissões no Host (WSL)

O problema mais comum com volumes montados no Docker (especialmente com cache de build como o do Angular/Vite) é a permissão negada (EACCES). Isso ocorre quando o usuário dentro do contêiner não tem permissão para escrever em arquivos ou diretórios montados a partir do seu sistema de arquivos do WSL.

Para mitigar isso:

Certifique-se de que nenhum contêiner esteja rodando.
No seu terminal WSL, na raiz do projeto (TalentLink/), execute os seguintes comandos para garantir que seu usuário no WSL seja o proprietário dos arquivos e tenha permissões de escrita:

sudo chown -R $USER:$USER ./*
sudo chmod -R u+rwX,go+rX,go-w ./*

Limpe caches e node_modules locais no WSL (para evitar que arquivos com permissões problemáticas sejam montados):

  rm -rf ./frontend-angular/node_modules
  rm -rf ./frontend-angular/.angular/cache
  rm -rf ./backend-nest/node_modules

5. Iniciando o Ambiente

Após configurar os arquivos e realizar as limpezas/correções de permissão:

Reinicie o Docker Desktop no Windows.
No seu terminal WSL, na raiz do projeto (TalentLink/), inicie os contêineres:

docker compose up -d --build --force-recreate

--build: Garante que as imagens Docker sejam reconstruídas com as últimas alterações nos Dockerfiles.
--force-recreate: Força a recriação dos contêineres, mesmo que não haja mudanças visíveis.

Abra o VS Code.
No VS Code, vá em File -> Open Folder... e selecione a pasta TalentLink/frontend-angular/. Quando perguntado "Reopen in Container", clique SIM.
Repita o passo 4 para a pasta TalentLink/backend-nest/.
Aguarde o VS Code se conectar aos contêineres e os postCreateCommand serem executados (você verá o log nos terminais do VS Code).
Após a inicialização, o frontend Angular estará acessível em http://localhost:4200 e o backend NestJS em http://localhost:3000.

6. Verificação e Depuração (Dentro do Contêiner)

Se houver problemas, você pode verificar o estado dos serviços dentro do contêiner:

No VS Code, abra um novo terminal (Terminal -> New Terminal).
Para o frontend (ou backend), execute:

Verificar processos: ps aux | grep "ng serve" (para frontend) ou ps aux | grep "node" (para backend).
Verificar portas: netstat -tulnp | grep 4200 (para frontend) ou netstat -tulnp | grep 3000 (para backend).

Este manual top deve servir como um guia robusto para configurar e manter seu ambiente. O hot-reloading funcionando é um grande alívio e um indicador de que as permissões e volumes estão no lugar certo.