riuri/node_api repository overview

⁠Atlas Library — API REST

O Atlas Library ajuda a gerenciar usuários, livros, autores, categorias, empréstimos, reservas e multas de uma biblioteca pública.

Esta é a imagem somente da API. Ela não inclui MySQL, o painel demonstrativo nem as dependências da suíte de testes. A versão 2.0.1 usa Node.js 22, Express e MySQL. O projeto é distribuído sob a GNU GPL v3.

⁠Escolha a imagem

A versão atual é riuri/node_api:2.0.1. Nesta publicação, latest aponta para a mesma imagem. Para uma instalação reproduzível, use o digest:

riuri/node_api@sha256:f76b49d188e863318ed64561d329e75d1149398e19c11a0a20255d078ef6bfbf

A imagem de execução está disponível para linux/amd64. latest é uma tag mutável: confira seu digest antes de atualizar uma instalação.

⁠Primeira instalação

Você precisa do Docker Compose, do SQL de inicialização e dos scripts do código correspondente à versão 2.0.1 no repositório GitHub⁠. Executar somente esta imagem com docker run não cria o MySQL, o schema nem os secrets.

Siga o tutorial de primeira instalação⁠. Ele cobre os secrets, SMTP, HTTPS local, inicialização do banco, criação do primeiro administrador e login com código por e-mail.

O repositório já inclui docker-compose.hub.yml, que substitui o build local da API pela imagem publicada e fixa o digest acima. Depois de preparar .local/compose.env e o certificado local conforme o tutorial, use Git Bash no Windows ou Bash no Linux:

projeto=atlas-primeira-instalacao
compose=(--env-file .local/compose.env -p "$projeto" \
  -f docker-compose.yml \
  -f docker-compose.hub.yml \
  -f docker-compose.https.yml)

docker compose "${compose[@]}" config --quiet
docker compose "${compose[@]}" build mysql_library
docker compose "${compose[@]}" pull node_api https_proxy
docker compose "${compose[@]}" up -d --no-build --wait --wait-timeout 180 node_api https_proxy
curl --cacert .local/tls/localhost.crt https://localhost:3443/health

Use um nome de projeto novo na primeira instalação e mantenha esse mesmo nome nas execuções seguintes: ele identifica o volume do banco. Não use down -v para parar ou atualizar uma instalação com dados.

O exemplo HTTPS usa Nginx, certificado local e portas em loopback apenas para testes locais. Configurar HTTPS para uma implantação pública é responsabilidade do operador. GET /health confirma que a API responde, mas não comprova sozinho a conexão com MySQL nem a entrega de e-mail.

⁠Configuração indispensável

• MySQL e API usam credenciais técnicas próprias, fornecidas por arquivos de secret. A API não deve usar a conta root do MySQL.
• A assinatura e a proteção do estado de autenticação exigem um secret forte e privado.
• Todo novo login exige senha e código por e-mail. Configure EMAIL_NOTIFICATIONS_ENABLED=true, EMAIL_USER e EMAIL_PASSWORD com SMTP funcional. Não existe código padrão nem bypass se o SMTP falhar.
• Não há administrador padrão. Cadastre uma conta comum e siga o tutorial para promovê-la pelo terminal autorizado da API.
• Não guarde dados importantes em library_tests: a suíte de integração pode limpar esse banco.

Consulte a referência de configuração⁠ e a referência da API⁠ para variáveis, permissões, requisições e respostas.

⁠Instalações com dados existentes

Não execute o SQL de primeira instalação sobre um banco existente. Para migrar da versão antiga identificada no procedimento de migração⁠ para 2.0.1, siga aquele procedimento: inventarie empréstimos, reservas e multas; interrompa a API e outros escritores; mantenha o MySQL ligado; verifique a restauração de um backup; só então aplique a migração e valide os dados.

A versão 2.0.0 já utiliza o schema da linha 2.x. A passagem de 2.0.0 para 2.0.1 não requer o SQL de migração: preserve o banco e seu backup ao substituir a API. A imagem antiga usada como origem da migração permanece disponível pelo digest indicado no guia e pela tag migration-source-v1.

⁠Testes e painel

A imagem de produção não inclui Jest. O guia de testes⁠ distingue testes sem banco, integração em banco exclusivo, smoke da API ativa e validação de migração e restauração.

O painel demonstrativo⁠ é opcional, local e não acompanha esta imagem. Ele não deve ser publicado como painel administrativo de produção.