Auto-hospedagem de carimbo de tempo Git com Docker Compose
O carimbo de tempo manual falha sempre da mesma forma. Alguém escreve um runbook, outra pessoa o transforma em script, o script roda por três semanas, um disco enche ou um token expira, e ninguém percebe até o dia em que um advogado pede provas de que seu repositório estava de determinada forma dezoito meses atrás.
A ancoragem em si não é a parte difícil. A parte difícil é o pipeline ao redor dela: detectar commits, agrupar hashes, sobreviver a reinicializações, entregar recibos e manter tudo verificável anos depois. É exatamente isso que uma stack Compose auto-hospedada oferece — uma implantação repetível e inspecionável em que a automação roda na sua rede e você é dono do diretório de dados.
Este artigo percorre a implantação do Timestamp GIT on-premises com Docker Compose, a conexão de um GitHub App uma única vez e a execução de um worker noturno automatizado que ancora seus hashes de commit no Bitcoin. Se você quiser primeiro o contexto conceitual, leia Cryptographic Prior Art: The Startup Shield Against Patent Trolls.
Por que auto-hospedar o carimbo de tempo Git?
Executar uma etapa de carimbo de tempo manualmente significa lembrar de três tarefas por repositório: obter os hashes de commit carimbados, coletar os arquivos de prova resultantes e armazená-los em algum lugar durável e auditável. Esqueça uma e a cadeia fica com lacunas; esqueça a etapa de armazenamento e você terá recibos que ninguém consegue localizar.
A auto-hospedagem atende a uma classe diferente de requisitos:
- Residência de dados. As equipes de compliance querem saber onde os metadados de commit são processados. Com a imagem Docker, a resposta é “no nosso host”.
- Redes restritas. Algumas equipes não concederão a nenhum SaaS acesso de leitura aos repositórios de código-fonte — nem mesmo somente leitura — independentemente do que um fornecedor prometa.
- Implantações próximas de air-gapped. Você pode executar a imagem em um host interno; apenas a etapa de ancoragem precisa de acesso de saída para os calendários públicos do OpenTimestamps.
- Controle operacional. Você decide a cadência de atualização, o cronograma de backup e quem pode acessar o assistente de configuração.
O Docker Compose é uma boa escolha porque o sistema inteiro são dois contêineres: a aplicação e uma instância Valkey usada como fila de hashes em memória. Um pull e um up -d colocam uma instância em execução; o volume ./data mantém o estado entre reinicializações; atualizar é docker compose pull && docker compose up -d.
Fundamentalmente, a imagem Docker é a mesma automação do produto hospedado — detecção de commits via GitHub App, ancoragem noturna no Bitcoin, recibos .ots enviados de volta ao seu repositório — apenas rodando na sua infraestrutura.
Configuração única: Docker Compose e GitHub App
Pré-requisitos
- Docker Engine com o plugin Compose.
- Um host com uptime confiável e acesso à internet de saída (necessário para ancoragem no Bitcoin via calendários públicos do OpenTimestamps).
- Um GitHub App que você possa instalar nos repositórios-alvo, e um repositório-alvo (ou repositório shadow) onde os branches de prova possam ser gravados.
- Um arquivo de licença para a instância.
O arquivo Compose
Uma configuração Docker Compose de início rápido tem esta aparência:
services:
timestampgit:
image: rue1401/timestampgit:prod
ports:
- "8080:8080"
volumes:
- ./data:/app/data
restart: unless-stopped
valkey:
image: valkey/valkey:8
restart: unless-stopped
Duas coisas a observar antes de prosseguir. O bind mount ./data:/app/data é o estado durável da instância — trate-o como dado crítico, não como cache. E restart: unless-stopped importa mais aqui do que de costume: o worker da meia-noite precisa estar vivo à meia-noite.
Inicie a stack:
docker compose pull
docker compose up -d
docker compose logs -f timestampgit
A aplicação fica disponível em http://localhost:8080 após a inicialização.
Primeira execução
Na primeira execução, um assistente de configuração orienta você na conexão do seu GitHub App e na configuração da instância. Planeje as permissões antes de clicar:
- Modo Standard. O GitHub App lê apenas o hash do commit HEAD de cada repositório monitorado e grava provas em um repositório-alvo. O modelo de permissões do GitHub exige pelo menos acesso somente leitura ao repositório de origem, além de acesso de leitura e escrita ao alvo.
- Modo Enterprise ZK. Uma GitHub Action de 12 linhas roda na sua infraestrutura e envia apenas o hash do commit para a API. Você precisa de acesso de leitura e escrita ao repositório-alvo e de nenhum acesso de leitura à origem.
Se você está avaliando isso em 2026 para uma equipe que já padronizou o fluxo de trabalho do GitHub App hospedado, as etapas de configuração parecerão familiares — consulte Automate Git Commit Timestamping With a GitHub App para esse caminho.
Licenciamento
Uma licença de demonstração por tempo limitado para avaliação está disponível enviando o formulário de solicitação na página Docker License com seu nome, empresa, e-mail e telefone opcional. Você pode baixar um arquivo de licença de demonstração por tempo limitado e enviá-lo durante a configuração Enterprise.
Se a instância for acessível de qualquer lugar além do localhost, coloque-a atrás de um proxy reverso com terminação TLS e restrinja o acesso na camada de rede. O assistente de configuração é uma superfície administrativa.
O pipeline automatizado: do commit à prova no Bitcoin
Depois que o GitHub App está conectado, o pipeline roda sozinho:
- Detecção de commits. O GitHub App recebe webhooks de novos commits ou — no Modo Enterprise ZK — sua GitHub Action envia hashes de commit para a API.
- Fila de hashes. Os hashes de commit chegam ao Valkey, o armazenamento chave-valor em memória usado para agrupamento.
- Worker cron da meia-noite. A cada noite, o worker agrupa todos os hashes pendentes, grava um manifesto
.txtpor repositório, constrói uma árvore de Merkle, cria provas OpenTimestamps usando calendários públicos OTS e ancora a raiz de Merkle no Bitcoin. - Entrega de provas. O manifesto e os arquivos de recibo
.otssão enviados de volta ao seu repositório em um branch dedicado de timestamps ou em um repositório shadow. - Confirmação. A confirmação no Bitcoin leva várias horas — normalmente cerca de três —, então a gravação das provas é concluída algumas horas após a execução do lote.
A propriedade de conhecimento zero é estrutural, não uma declaração de política: apenas hashes de commit são processados. Seja no Modo Standard ou no Modo Enterprise ZK, seu código-fonte nunca sai da sua rede. A implantação Docker simplesmente move a etapa de processamento de hashes para dentro do seu perímetro também.
Como a raiz de Merkle é ancorada em um bloco do Bitcoin via OpenTimestamps, o carimbo de tempo se torna imutável após a confirmação. Nenhuma entidade pode alterá-lo ou forjá-lo — incluindo o fornecedor e incluindo você.
Monitoramento e tratamento de falhas
Um pipeline de carimbo de tempo falha silenciosamente. Os hashes de commit se acumulam na fila, nada dá erro, e você descobre a lacuna durante uma auditoria. Trate o monitoramento como parte da implantação.
Saúde do contêiner e da fila. A verificação mais útil é o próprio status da aplicação para um repositório conhecido. Aponte seu monitor de uptime para ele:
#!/usr/bin/env bash
set -euo pipefail
BASE="http://localhost:8080"
USER="acme"
REPO="platform"
docker compose ps --status running --quiet timestampgit >/dev/null \
|| { echo "timestampgit container is not running"; exit 1; }
curl -fsS "$BASE/api/statusLast/$USER/$REPO" | jq .
GET /api/statusLast/{user}/{repo} retorna as informações do último bloco do Bitcoin ancorado. Se esse bloco parar de avançar, o worker está travado.
Badges públicos de verificação. Para cada repositório monitorado, o widget de badge gera markdown Shields.io incorporável para o seu README. O trecho é servido por GET /api/badgeLink/{user}/{repo} (autenticado) e se parece aproximadamente com:
[](https://timestampgit.dev/status/acme/platform)
Qualquer pessoa pode seguir o link para verificar o carimbo de tempo pelo site. Para repositórios privados, a URL de status carrega um HMAC criptografado específico da sua instância de servidor, de modo que apenas usuários autorizados podem ler o status.
Auditoria e relatórios. Extraia o livro-razão em um cronograma, em vez de sob demanda:
curl -fsS -o audit-$(date +%F).csv "$BASE/api/audit/$USER/$REPO"
curl -fsS -o report-$(date -d yesterday +%F).pdf \
"$BASE/api/report/$USER/$REPO/$(date -d yesterday +%F)"
Isso fornece um livro-razão de auditoria em CSV e um certificado PDF por data que as equipes jurídica e de compliance podem arquivar sem acessar a API diretamente.
Atrasos de confirmação. A ancoragem normalmente se resolve em cerca de três horas. Atrasos acontecem; o worker tenta novamente e entrega a prova .ots assim que a âncora é confirmada. Crie alertas para “manifesto gravado, mas nenhum recibo após 24 horas” em vez de para atrasos curtos, caso contrário você será acionado por variações normais de blocos do Bitcoin.
Backup e restauração. Faça backup de ./data em um cronograma e monte um volume nomeado para o diretório /data do Valkey se quiser que os hashes enfileirados sobrevivam à recriação de um contêiner. O Valkey é um armazenamento em memória por design — perdê-lo custa o lote de uma noite, não suas provas existentes, porque as provas entregues ficam no branch de timestamps.
Boas práticas para carimbo de tempo auto-hospedado
- Dedique um host. O worker roda à meia-noite e precisa de uptime estável e conectividade de saída. Compartilhar um host com uma build farm ruidosa é pedir um lote perdido.
- Mantenha o volume de dados fora de armazenamento efêmero. Faça bind mount de
./dataem disco durável e inclua-o na sua rotação de backups. - Restrinja a superfície administrativa. Coloque o assistente e a API autenticada atrás da sua VPN ou proxy reverso com autenticação forte. Não exponha a porta 8080 à internet pública.
- Atualize deliberadamente. Execute
docker compose pullem um cronograma que você controla; leia o changelog antes de baixar uma nova imagem:prod. - Prefira o Modo Enterprise ZK quando as permissões forem contestadas. Se sua equipe de segurança não conceder acesso de leitura aos repositórios de origem, o caminho da GitHub Action os satisfaz sem alterar a automação.
- Documente o processo para auditores. Anote onde a instância roda, quem a administra, como os backups são verificados e onde os recibos
.otssão armazenados. A prova é criptográfica; a cadeia de custódia ainda precisa de um parágrafo. - Teste uma verificação de ponta a ponta. Escolha uma data ancorada e percorra o fluxo de verificação antes de precisar dele em uma disputa, não durante uma. Para o enquadramento jurídico, consulte Is a Bitcoin Timestamp Admissible as Evidence? A Compliance Guide.
Perguntas frequentes
Preciso expor meu código-fonte ao Timestamp GIT? Não. O Timestamp GIT processa apenas hashes de commit. No Modo Standard, o GitHub App lê o hash do commit HEAD; no Modo Enterprise ZK, uma GitHub Action envia apenas o hash a partir da sua infraestrutura. Seu código-fonte nunca sai da sua rede.
O que acontece se a confirmação no Bitcoin levar mais tempo que o esperado?
O worker cron da meia-noite ancora a raiz de Merkle no Bitcoin via OpenTimestamps. A confirmação normalmente leva cerca de 3 horas. Se a confirmação atrasar, o worker tentará novamente e entregará a prova .ots assim que confirmada.
Posso usar isso em um ambiente air-gapped? Sim, a imagem Docker pode rodar em um ambiente air-gapped, mas o acesso à internet de saída é necessário para a ancoragem no Bitcoin via calendários públicos do OpenTimestamps. Você pode configurar o acesso à rede de acordo.
Como verifico um carimbo de tempo de forma independente?
Você pode baixar o arquivo .ots e verificá-lo com ferramentas padrão de verificação do OpenTimestamps contra a blockchain do Bitcoin. Como alternativa, use a página de verificação fornecida pelo Timestamp GIT, que realiza a verificação local no seu navegador — ninguém vê o que você verifica.
Conclusão
Auto-hospedar o carimbo de tempo Git não se trata de desconfiar de um fornecedor; trata-se de colocar um pipeline automatizado e auditável dentro de um limite que sua equipe de compliance já aceita. Dois contêineres, um arquivo de licença, um GitHub App — e depois disso o worker da meia-noite faz a parte repetitiva enquanto você obtém um repositório cheio de recibos .ots e uma página de status pública.
Comece solicitando uma licença de demonstração na página Docker License, suba a stack Compose em um host de staging e verifique um dia ancorado de ponta a ponta. Se você preferir pular a infraestrutura, o Timestamp GIT GitHub App gerenciado oferece a mesma ancoragem noturna sem nenhuma configuração — e você pode migrar para auto-hospedado depois sem alterar o que chega ao seu repositório.
Posts relacionados
- Cryptographic Prior Art: The Startup Shield Against Patent Trolls
- Is a Bitcoin Timestamp Admissible as Evidence? A Compliance Guide
- How to Prove You Shipped a Feature Before a Competitor