Pular para o conteúdo principal

Instalação

Este guia fornece instruções detalhadas para instalar e configurar o APAH Assistant no seu ambiente de desenvolvimento.

Requisitos do Sistema​

Software Necessário​

SoftwareVersão MínimaRecomendada
Node.js20.022.x LTS
pnpm8.09.x
Docker20.0Latest
Docker Compose2.0Latest
PostgreSQL1516

Sistemas Operativos Suportados​

  • macOS 12 (Monterey) ou superior
  • Linux Ubuntu 22.04 ou equivalente
  • Windows 11 com WSL2

Instalação Passo a Passo​

1. Instalar Node.js​

Recomendamos usar o nvm para gerir versões do Node.js:

# Instalar nvm
curl -o- https://raw.githubusercontent.com/nvm-sh/nvm/v0.39.0/install.sh | bash

# Instalar Node.js 22
nvm install 22
nvm use 22

2. Instalar pnpm​

# Usando npm
npm install -g pnpm

# Ou usando corepack (recomendado)
corepack enable
corepack prepare pnpm@latest --activate

3. Instalar Docker​

macOS​

# Usando Homebrew
brew install --cask docker

Linux (Ubuntu/Debian)​

# Instalar Docker
sudo apt-get update
sudo apt-get install docker-ce docker-ce-cli containerd.io docker-compose-plugin

# Adicionar utilizador ao grupo docker
sudo usermod -aG docker $USER

4. Clonar o Repositório​

git clone https://github.com/Visual-Thinking/apah-assistant.git
cd apah-assistant

5. Instalar Dependências​

pnpm install

Isto irá instalar todas as dependências definidas no package.json.

6. Configurar Base de Dados​

Usando Docker Compose (Recomendado)​

O projeto inclui um ficheiro docker-compose.yaml configurado para PostgreSQL:

# Iniciar containers
docker-compose up -d

# Verificar se está a correr
docker-compose ps

Configuração Manual do PostgreSQL​

Se preferir usar uma instalação local do PostgreSQL:

# Criar base de dados
createdb apah_assistant

# Configurar a connection string no .env
DATABASE_URL="postgresql://user:password@localhost:5432/apah_assistant"

7. Executar Migrações​

# Gerar migrações (se necessário)
pnpm db:generate

# Aplicar migrações
pnpm db:migrate

O projeto inclui scripts de seed para dados iniciais:

# Executar seeds
pnpm db:seed

Verificar Instalação​

Execute os seguintes comandos para verificar que tudo está configurado corretamente:

# Verificar tipos TypeScript
pnpm typecheck

# Verificar linting
pnpm check

# Iniciar em modo de desenvolvimento
pnpm dev

Se a aplicação iniciar sem erros, a instalação foi bem-sucedida!

Resolução de Problemas​

Erro: "Cannot find module"​

# Limpar cache e reinstalar
rm -rf node_modules
pnpm install

Erro de conexão à base de dados​

  1. Verifique se o Docker está a correr: docker ps
  2. Verifique a connection string no .env
  3. Tente reiniciar os containers: docker-compose restart

Erros de permissão no Docker (Linux)​

sudo usermod -aG docker $USER
# Fazer logout e login novamente

Próximos Passos​