Ir para o conteúdo

Pipeline de deploy — permissões do utilizador coaching

A página de administração Deploy executa comandos como o mesmo utilizador Unix que o Next.js / pm2 (normalmente coaching). Segue-se o que esse utilizador precisa de poder fazer.

Versão do Node.js (npm warn EBADENGINE)

O package.json declara "engines": { "node": ">=22.0.0", "npm": ">=10.0.0" }. O repositório fixa Node 24 no .nvmrc (produção / equipa). Parte da toolchain Prisma e pacotes de testes já indicam ^22.12 || >=24 — Node 24 cobre tudo sem avisos.

Se em produção estiveres em Node 20 (ou mais antigo), o npm install no Deploy mostra EBADENGINE Unsupported engine — por defeito o npm continua a instalar, mas estás fora do intervalo suportado e deves actualizar.

Corrigir no servidor

  1. Instala Node.js 24 (a mesma major na shell e no pm2 — o pm2 usa o binário node com que foi iniciado). O mínimo suportado pelo projecto é 22; não permaneças no 20.

Opção A — nvm (utilizador coaching ou de deploy):

curl -o- https://raw.githubusercontent.com/nvm-sh/nvm/v0.40.1/install.sh | bash
source ~/.nvm/nvm.sh
nvm install 24
nvm alias default 24
node -v   # v24.x

Opção B — NodeSource / pacotes da distro — usa pacotes Node 24 (ou pelo menos 22) para /usr/bin/node cumprir engines.

  1. Reinstala globais se precisares (npm i -g pm2), depois pm2 restart / pm2 reload na mesma sessão onde node -v coincide com produção.

  2. Opcional: engine-strict=true no .npmrc no CI — não recomendado no servidor até o Node estar actualizado.

Não “corrigir” só o package.json

Baixar engines para Node 20 remove o aviso do pacote coach-studio, mas dependências transitivas (ex.: @prisma/streams-local) podem continuar a reportar EBADENGINE até o Node ser realmente ≥ 22.

Se o PM2 corre sob systemd, coloca o bin do Node no início do PATH da unidade — ver PM2 systemd e Node.js.

Repositório e ficheiros gerados

  • Leitura e escrita em todo o clone (p.ex. /var/www/coaching), incluindo:
  • apps/docs/site/ — recriado por mkdocs build em cada deploy.
  • O ideal é o clone ser dono coaching para o build não precisar de sudo para escrever HTML.
  • Se algum npm/chown antigo deixou ficheiros root-owned (erro típico EACCES unlink sharp), o deploy corre deploy/fix-ownership-from-deploy.sh antes do npm ci.

Corrigir ownership automaticamente no deploy

  1. Uma vez no servidor (como root):
sudo bash /var/www/coaching/deploy/fix-ownership.sh
  1. Opcional — permitir o passo no Deploy sem palavra-passe:
sudo visudo -f /etc/sudoers.d/coaching-ownership

coaching ALL=(root) NOPASSWD: /bin/bash /var/www/coaching/deploy/fix-ownership.sh

Sem esta linha, se existirem ficheiros root-owned o passo falha com instruções (em vez de falhar depois no npm com EACCES).

O que cada área precisa

Área Requisito
Git / npm / Node / Prisma / Next Comandos no PATH; sem privilégio Unix extra.
Ownership (deploy/fix-ownership-from-deploy.sh) sudo só se configuraste fix-ownership.sh sem palavra-passe (acima). Caso contrário, o clone deve já ser dono coaching.
MkDocs (apps/docs/build-from-deploy.sh) python3 com venv, permissão de escrita em apps/docs/.venv/ e apps/docs/site/.
Cron systemd (deploy/cron/install-from-deploy.sh) sudo só se configuraste install.sh sem palavra-passe — ver deploy/cron/README.md. Caso contrário o passo imprime SKIP e termina com sucesso.

Python / virtualenv do MkDocs

O script de deploy mantém o MkDocs isolado em apps/docs/.venv:

cd /var/www/coaching
bash apps/docs/build-from-deploy.sh

Cria a venv se não existir, instala apps/docs/requirements.txt nessa venv e corre mkdocs build a partir dela. Isto evita falhas PEP 668 em Debian / Ubuntu e não instala pacotes Python no ambiente do sistema.

Se o servidor não tiver suporte de venv instalado, instala uma vez, por exemplo sudo apt install python3-venv.

Resumo

Privilégio Para quê
Utilizador normal (coaching) dono do repo git pull, npm, build Next, saída MkDocs, reload pm2
Escrita em apps/docs/.venv/ e apps/docs/site/ Dependências MkDocs e documentação estática gerada
sudo sem palavra-passe só para deploy/fix-ownership.sh Opcional — corrigir ficheiros root-owned no deploy
sudo sem palavra-passe só para deploy/cron/install.sh Opcional — actualizar unidades systemd no deploy

Root (sudo) não é necessário para o build da documentação se coaching puder escrever em apps/docs/site/.