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" }. Parte da toolchain Prisma também espera Node ≥ 22.

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 22 LTS (a mesma major na shell e no pm2 — o pm2 usa o binário node com que foi iniciado).

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 22
nvm alias default 22
node -v   # v22.x

Opção B — NodeSource / pacotes da distro — usa pacotes Node 22 para /usr/bin/node ser v22.

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

  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:
  • documentation/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.

O que cada área precisa

Área Requisito
Git / npm / Node / Prisma / Next Comandos no PATH; sem privilégio Unix extra.
MkDocs (documentation/build-from-deploy.sh) python3, python3 -m pip, permissão de escrita em documentation/site/. Escrita opcional para instalações pip (ver secção seguinte).
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 / pip e --break-system-packages

O script de deploy executa:

python3 -m pip install -r documentation/requirements.txt --break-system-packages -q
mkdocs build -q

Em Debian / Ubuntu recentes, o Python do sistema está externamente gerido (PEP 668), pelo que pip install sem venv falha a menos que uses --break-system-packages ou um ambiente virtual.

A flag permite ao utilizador coaching instalar MkDocs, mkdocs-material e mkdocs-static-i18n nesse Python sem sudo. Contrapartida: os pacotes ficam no Python partilhado usado por python3 (aceitável num servidor dedicado à app).

Alternativa com isolamento

Para maior isolamento, cria documentation/.venv uma vez (como coaching), corre pip install -r requirements.txt dentro dele e altera documentation/build-from-deploy.sh para fazer source .venv/bin/activate antes de mkdocs build, sem --break-system-packages.

Resumo

Privilégio Para quê
Utilizador normal (coaching) dono do repo git pull, npm, build Next, saída MkDocs, reload pm2
pip install … --break-system-packages Dependências MkDocs em máquinas PEP 668 sem venv
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 documentation/site/.