Timestamp GIT

← Todos os artigos

2026-11-13

Carimbo de Tempo Git Auto-Hospedado com Docker Compose

Carimbo de Tempo Git Auto-Hospedado com Docker Compose
timestamp git blockchain proof

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:

  1. 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.
  2. Fila de hashes. Os hashes de commit chegam ao Valkey, o armazenamento chave-valor em memória usado para agrupamento.
  3. Worker cron da meia-noite. A cada noite, o worker agrupa todos os hashes pendentes, grava um manifesto .txt por 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.
  4. Entrega de provas. O manifesto e os arquivos de recibo .ots são enviados de volta ao seu repositório em um branch dedicado de timestamps ou em um repositório shadow.
  5. 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:

[![Timestamped in Bitcoin](https://img.shields.io/endpoint?url=https://timestampgit.dev/api/statusSummary/acme/platform)](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 ./data em 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 pull em 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 .ots sã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

EU label: AI-generated content