Aplicações Dockerizadas

Todas as apps do H1 são empacotadas como imagens Docker e publicadas no GHCR (GitHub Container Registry), privado, sob ghcr.io/hasarbrasildesenvolvimento/…. A CI de cada repo builda e versiona; quem vai rodar (nós ou o cliente) só puxa a imagem com um token de leitura.

Quais imagens existem

Imagem	Repo(s)	O que é
`hsbr-gestao-ativos-back` (+ `…-back:*-sqlserver`)	HSBR-Gestao-Ativos-Back	API do Gestão de Ativos. Duas variantes por engine (Postgres / SQL Server), buildadas em matrix.
`hsbr-gestao-ativos-front`	HSBR-Gestao-Ativos-Front	Front (Next.js) do Gestão de Ativos.
`middleware-rfid`	Middleware-RFID-Back (+ -Front)	Imagem única combinada: o back (Express + bridge TCP) serve o front (React) na mesma porta. Sem banco/Redis externo (SQLite em volume).

Como são publicadas (CI → GHCR)

Cada repo tem um workflow publish-ghcr que builda e dá push da imagem. Ele dispara em:

push no branch ativo (ex.: main/develop no Gestão de Ativos; refactor-arq2-eventos no middleware) e em branches cliente*;
release publicada;
manual (workflow_dispatch).

Tags geradas pela docker/metadata-action:

Tag	Quando	Mutável?
`<branch>` (ex.: `main`, `refactor-arq2-eventos`)	a cada push no branch	sim (anda com o branch)
`sha-<commit>`	a cada build	não (imutável)
`vX.Y.Z`	só em release (ou dispatch, veja abaixo)	não

Middleware: front de outro repo

A imagem do middleware é combinada, mas o front vive em outro repo. A CI da back faz checkout cross-repo do front usando uma deploy key read-only (secret FRONT_DEPLOY_KEY) e bakeia o dist/. Deploy key ≠ token de pull: ela serve só pra CI clonar o outro repo, não pro cliente.

Versionamento (release-please + semver)

Usamos release-please com Conventional Commits: feat: sobe minor, fix: sobe patch, ci:/chore: não versionam. O fluxo:

Commits vão pro branch principal.
O release-please mantém um PR de release aberto (atualiza CHANGELOG + versão). Ao mergear esse PR, cria a Release + a tag vX.Y.Z.
A Release deveria disparar o publish-ghcr para publicar …:vX.Y.Z.

O "gap" da tag semver

O release-please cria a Release usando o GITHUB_TOKEN, e esse evento não dispara outro workflow (regra anti-cascata do GitHub). Então …:vX.Y.Z não sai sozinha. Duas saídas:

# (a) publicar a tag semver manualmente, após a release:
gh workflow run publish-ghcr.yml --repo HasarBrasilDesenvolvimento/<REPO> \
  --ref <branch> -f semver_tag=v1.2.3

(b) permanente: dar um PAT RELEASE_PAT ao release-please-action — aí o evento release: published cascateia e o type=semver publica automático.

Enquanto isso, sha-<commit> é sempre imutável e serve pra fixar produção sem depender da tag semver.

Tokens: como um cliente (ou host) puxa a imagem

As imagens são privadas. Para puxar, precisa de um GitHub PAT com escopo read:packages (o mesmo tipo usado para o SDK; veja também DevOps & Deploy → Autorização).

Onde o token entra, por cenário:

Cenário	Como usar o token
Deploy do Gestão de Ativos (scripts)	`DevOps/docker/.env.secrets` → `GITHUB_NPM_TOKEN` (os scripts fazem `docker login`)
Middleware RFID (compose)	`DevOps/docker/middleware/.env` → `GHCR_USER` + `GHCR_TOKEN` (o `run.sh` faz `docker login`)
Kubernetes	`kubectl create secret docker-registry ghcr …` (imagePullSecret)
Manual	`echo <TOKEN> \| docker login ghcr.io -u <user> --password-stdin`

Fornecer a um cliente: crie um PAT classic com só read:packages (Settings → Developer settings → Tokens classic), e entregue por canal seguro junto do usuário dono. O cliente usa como acima. Rotacione se vazar.

docker login falhando com "denied" mesmo com token válido?

Em algumas máquinas (ex.: Docker Desktop com credential helper problemático) o docker login falha apesar do token estar OK. Contorne puxando com um config isolado, sem o helper:

mkdir -p /tmp/dcfg
printf '{"auths":{"ghcr.io":{"auth":"%s"}}}' \
  "$(printf '%s:%s' <user> <TOKEN> | base64 -w0)" > /tmp/dcfg/config.json
docker --config /tmp/dcfg pull ghcr.io/hasarbrasildesenvolvimento/<imagem>:<tag>

Como rodar cada uma

Middleware RFID (imagem única)

Deploy pronto em DevOps/docker/middleware/:

cd DevOps/docker/middleware
cp .env.example .env      # preencha GHCR_USER, GHCR_TOKEN e (opcional) TAG/portas
./run.sh up               # login + pull + up -d + healthcheck
# UI/API:   http://localhost:4141
# Leitores: <IP-do-host>:5555 (TCP)

./run.sh também tem down, logs, ps, pull, login, restart. Persiste em SQLite no volume middleware-data. Detalhes no DOCKER.md do repo Middleware-RFID-Back e no README.md da pasta.

Gestão de Ativos

Vários caminhos, cada um com sua página:

VPS / servidor (imagens GHCR + docker compose profile-aware) → DevOps & Deploy.
On-premise / air-gap (bundle docker save/load + licença offline) → Implantação On-Premise.
Kubernetes (manifests + imagePullSecret + licença como Secret) → DevOps/k8s/ (genérico + exemplo por cliente).

Resumo do fluxo

commit → CI publish-ghcr → GHCR (privado)
                              │  tags: <branch>, sha-<commit>, vX.Y.Z (release)
                              ▼
        cliente/host: docker login (PAT read:packages) → pull → run

Tudo mora no GitHub: código + CI que builda + registry (GHCR) que hospeda as versões. A entrega ao cliente é só a imagem + um token de leitura.

Quais imagens existem​

Como são publicadas (CI → GHCR)​

Versionamento (release-please + semver)​

Tokens: como um cliente (ou host) puxa a imagem​

Como rodar cada uma​

Middleware RFID (imagem única)​

Gestão de Ativos​

Resumo do fluxo​