Skip to content

About

Operação de API e worker em Docker: isolamento, backups, restauração, TLS, release e rollback.

Topics

Resources

Security policy

Stars

0 stars

Watchers

0 watching

Forks

Repository files navigation

ContainerOps

API de jobs com worker, fila no PostgreSQL e ferramentas de backup, restore e troca de versão. O relatório local reúne os resultados das operações e os jobs observados.

Demonstração Arquitetura Executar localmente Verificação e evidências Arthur Joanes no LinkedIn

Visão geral

A API recebe texto; um worker conta palavras e calcula o SHA-256 dos bytes; PostgreSQL guarda fila e resultado. O cálculo pequeno permite conferir o que aconteceu depois da recuperação. Textos e falhas são sintéticos; HTTP, processos e banco executam localmente no mesmo computador.

Pelo contrato, a mesma chave e conteúdo recuperam o job existente; conteúdo diferente conflita. O repositório transacional controla uma posse temporária (lease) e seu token, impedindo que um worker antigo sobrescreva a aquisição atual.

Demonstração

Jobs observados por período, estados e duração de cada operação no relatório local

Filtre os jobs por data UTC, compare os estados registrados e consulte a duração de backup, restore e troca de imagem. Cada valor mantém um link para seu JSON. O exemplo usa os registros de 12/10/2026; abrir a página não consulta os serviços.

O catálogo permite buscar uma cópia por ID ou origem e conferir integridade e recibo de restore. Os detalhes incluem os comandos para operar aquela cópia.

Abrir o relatório local · catálogo de cópias · catálogo no celular · guia de leitura.

A sequência operacional detalha recuperação do worker, restauração e rollback, com os registros de cada cenário.

Arquitetura

flowchart TB
  C["Cliente<br/>Bearer + chave idempotente"] -->|"HTTP :8105"| P
  subgraph FRONT["Rede front"]
    P["NGINX :8080<br/>limita entrada HTTP"]
    A["FastAPI :8000<br/>owner + contrato do job"]
    P -->|"POST / GET jobs"| A
  end
  subgraph DATA["Rede data interna"]
    D[("PostgreSQL · pgdata<br/>fila, lease e resultado")]
    W["Worker<br/>contagem Unicode + SHA-256"]
    W -->|"claim / conclusão com token"| D
  end
  A -->|"SQL: admissão e consulta"| D
  O["CLI ops.py<br/>migração e backup"] -->|"pausa / dreno / pg_dump"| D
  O --->|"dump + restore-test"| T[("Volume novo<br/>dados + job de verificação")]
  O -.->|"evidências → report.py"| R["Relatório HTML<br/>execuções identificadas"]
Loading

As setas contínuas representam chamadas e transferência de dados; as pontilhadas, geração de evidências. A API pertence às redes front e data; worker e banco apenas à data. API e worker usam a mesma imagem em processos separados. PostgreSQL guarda a fila e o resultado na mesma linha; o worker busca trabalho no banco, sem chamada direta da API. O Compose mantém todos os serviços no mesmo host e publica HTTP em loopback; o banco não publica porta no host.

Responsabilidade Implementação e garantia
Aceitar e consultar API + repository: UNIQUE(owner, idempotency_key), comparação do conteúdo e limite de 100 pendentes globais/20 por owner na transação. Corpo até 32 KiB e texto até 16 KiB. Retorna 201 para criação, 200 para replay e 409 para conteúdo divergente.
Executar e recuperar Worker: despacho favorece o owner menos recentemente ativo; calcula fora da transação e só grava com lease de 5 s/token válidos. Trabalho interrompido pode repetir, até três tentativas.
Persistir e operar Conexões e CLI: papéis distintos para DML, migração e backup. Guarda dump/hash/snapshot no runtime local e restaura em volume novo. Release troca API/worker; rollback preserva o schema expansivo.
Observar e apresentar Logs estruturados, healthchecks e métricas internas; relatório lê arquivos de execuções identificadas e apresenta evidências estáticas.

O job passa por POST autenticado → admissão transacional → queued → claim com lease → cálculo → succeeded → GET pelo mesmo owner. Se o worker morrer, o próximo claim após expirar a lease conserva o ID e incrementa a tentativa. Sequências, permissões e recuperação mostram o caminho normal e as operações de manutenção.

Stack e decisões

Python FastAPI Pydantic PostgreSQL NGINX Docker BuildKit Trivy HTML CSS JavaScript

Escolha Motivo e compromisso
FastAPI + worker Python Separa admissão de cálculo; exige posse, renovação e tentativas.
Pydantic Valida o corpo recebido pela API, incluindo tipo, tamanho e caracteres do texto, antes de aceitar um job.
PostgreSQL Reúne fila, estado e transações; API e fila disputam recursos.
NGINX + Compose Entrada HTTP/TLS e processos separados; não protege contra perda do host.
BuildKit + Trivy BuildKit gera as imagens e suas attestations; Trivy verifica vulnerabilidades conhecidas nos artefatos. Um scan registra os achados daquela imagem e base.
HTML, CSS e JavaScript Relatório local com resultados registrados; estilos e navegação são empacotados junto do HTML.

Decisões, código e testes · bases fixadas por digest. Versões fixadas não significam versões mais recentes.

Executar localmente

Use Docker com containers Linux em x86-64, Compose v2, Buildx e Python 3.11+. São os requisitos adotados pelos comandos, imagens e CI. Primeiro build e scan precisam baixar dependências.

python3 scripts/ops.py setup
python3 scripts/ops.py build
python3 scripts/ops.py verify
python3 scripts/ops.py start
python3 scripts/ops.py demo
python3 scripts/ops.py report

No Windows, use python ou o wrapper PowerShell, com Docker Desktop em modo Linux. O Compose publica a API em localhost:8105. Jobs exigem Bearer; o setup gera tokens fictícios fora do Git, conforme o roteiro.

Runbooks detalham backup, restore-test, release, rollback, scan e o runtime. stop preserva o volume; um comando de limpeza deve usar o projeto e o destino identificados pela operação.

Operar em um contexto separado

Defina CONTAINEROPS_SESSION antes de executar a CLI. No Windows, o contexto fica em %USERPROFILE%\AppData\Local\ContainerOps-runtime\sessions\<slug>; a demonstração sem sessão conserva seu runtime e nomes. Use um basename de até 32 caracteres, com letras minúsculas, dígitos e hífens, sem hífen nas extremidades. Links, junções, traversal e caminhos externos são recusados.

$env:CONTAINEROPS_SESSION = 'backup-lab-20261012'
python scripts/ops.py setup
python scripts/ops.py build --version 1.0.0
python scripts/ops.py build --version 2.0.0
python scripts/ops.py verify
python scripts/ops.py prove --scenario operations

O contexto tem lock, segredos, builder, tags, cache e evidências próprios. Portas dos novos ambientes usam loopback e portas livres. Docker, CPU e memória continuam compartilhados; execute builds, scans e carga em sequência. O relatório da sessão fica em sessions/<slug>/docs/report.html, junto de suas evidências. Os aliases históricos do repositório permanecem separados.

Transportar e selecionar backups

backups list mostra IDs, origem, integridade e proteção. backup-export --backup <id> --destination <pasta-nova> cria um pacote privado com dump, metadados e manifesto versionado. backup-import --source <pacote> confere os bytes e registra outra cópia no contexto ativo, sem restaurar nem carregar imagens. Use o ID retornado em restore-test --backup <id> --trusted-source para um pacote de origem confiável. O comando sem --backup conserva a seleção pelo ponteiro legado.

A opção --include-image exporta a imagem de aplicação por ID. Seu carregamento exige backup-image-load --backup <id> --trusted-image-source, em uma sessão; a tag aplicada pertence somente a essa sessão. Imagens auxiliares compatíveis precisam estar preparadas no destino. Formato, limites e roteiro.

backups prune --keep-last 3 gera uma prévia. Remoção exige --apply --plan-id <id-do-plano> e nova conferência sob lock. Latest, marcas de proteção, última cópia válida e último restore verificado por origem são preservados. A retenção dos jobs no banco é independente da retenção desses arquivos.

Verificação e evidências

A rodada de 12/10/2026 registra exportação/importação de backup, snapshot restaurado, novo job, TLS, release e rollback em ambientes descartáveis. O transporte foi testado entre contextos no mesmo host. Resultados e limites · relatório original.

Pergunta Fonte e data da execução Limite
Worker interrompido recupera o job? Antes/depois do SIGKILL, 22/09/2026, 12:36 UTC Mesmo ID concluiu na tentativa 2; cálculo pode repetir.
Os dados voltam após restore? Restore JSON, 22/09/2026, 12:38 UTC Três jobs comparados e novo trabalho concluído; volume novo no mesmo host.
A admissão se distribui entre owners? Manifesto da medição, 22/09/2026, 06:12 a 06:15 UTC Três repetições: 120 aceitos/concluídos e 24 recusados; cenário local com dois owners.

Para repetir a prova completa, prepare antes a base Trivy com scan; Docker e OpenSSL são necessários:

python scripts/ops.py prove

O runner cria projetos descartáveis e registra manifestos por tentativa. Para executar somente job, rollback e restauração com as imagens já preparadas:

python scripts/ops.py prove --scenario operations

Verificação e histórico de correções · fontes e afirmações.

Limites e segurança

  • 16 KiB por texto; 100 jobs pendentes globais; 20 por owner; 3 tentativas; retenção de 24 h. São limites do contrato, implementados no domínio e no repositório; não medem capacidade.
  • A demo permite atraso de até 15 s; DEMO_MODE=false aceita duração zero. A distribuição não interrompe jobs em execução nem garante prazo. Configuração e validação.
  • Backup local compartilha a falha do computador. O pacote permite transporte; proteção contra perda do host exige cópia física e destino independentes, ainda fora da prova local. TLS termina no proxy; rollback troca imagens sem rebaixar schema. Runbooks.
  • O scanner bloqueia HIGH/CRITICAL, inclusive sem correção. Um resultado sem achados vale para imagem/base/data registradas. Política e escopo.
  • A revisão de segurança de 03/10/2026 registra a avaliação de 18 itens de segurança, rate limit, prazo total do corpo, erros privados e testes com banco descartável.

Documentação

Para entender Guia
Problema, componentes e escolhas Casos · arquitetura · decisões
API, fila e idempotência Contrato de dados
Executar e recuperar Demonstração · runbooks · recuperação
Conferir resultados e fontes Verificação · admissão · fontes e datas
Relatório e manutenção Guia do relatório · identidade e fontes locais · manutenção · capturas

Autor e licença

Para conversar sobre containers, recuperação e operação deste laboratório:

Arthur Joanes no LinkedIn

Licença MIT. Ícones Devicon e LinkedIn: licença MIT. Trivy e Pydantic: Simple Icons, CC0 1.0.

Fontes dos ícones e cartões: documentação da stack.

About

Operação de API e worker em Docker: isolamento, backups, restauração, TLS, release e rollback.

Topics

Resources

Security policy

Stars

0 stars

Watchers

0 watching

Forks

Releases

Packages

Contributors

Languages