Carimbo de Tempo Git Auto-Hospedado com Docker: Um Guia

A tarefa manual repetitiva que você está eliminando é esta: toda vez que você quer uma prova criptograficamente defensável de que um commit Git existia em uma determinada data, ou você executa comandos de carimbo de tempo manualmente ou envia metadados para um serviço que você não controla totalmente. Para startups, empresas de desenvolvimento e equipes preocupadas com conformidade, isso cria uma lacuna. Etapas manuais são ignoradas. Dependências externas levantam questões de soberania de dados. Ambientes regulamentados ou isolados muitas vezes não podem usar um SaaS gerenciado de forma alguma.

O caminho difícil é executar o OpenTimestamps você mesmo e cuidar de cada recibo. O caminho prático é implantar o Timestamp GIT como uma aplicação Docker auto-hospedada: a mesma automação baseada em GitHub App, ancoragem noturna em Bitcoin e selos de verificação rodam em infraestrutura que você possui.

Se você precisa de uma revisão sobre por que a prova de existência é importante em software antes de continuar, consulte Prova de Existência em Software: Um Guia para Iniciantes.

Por que Auto-Hospedar o Carimbo de Tempo Git?

Auto-hospedar o Timestamp GIT não é sobre evitar o serviço gerenciado. É sobre executar a automação idêntica atrás do seu próprio firewall, com seu próprio volume de dados, sua própria licença e suas próprias regras de rede. Isso importa quando:

• Você precisa de soberania de dados e não quer que metadados de commit saiam do seu ambiente além da etapa de ancoragem em Bitcoin.
• Você opera em um ambiente regulamentado ou isolado onde conexões com SaaS de terceiros são restritas.
• Você quer controle total sobre as credenciais do GitHub App, local de armazenamento e acesso aos logs.
• Você precisa de uma implantação auditável que permaneça sob o controle operacional da sua equipe.

A opção Docker auto-hospedada oferece o mesmo pipeline automatizado: instale o GitHub App uma vez, conecte repositórios e deixe a instância agrupar hashes de commit a cada noite, construir provas Merkle e ancorá-las no Bitcoin. Após a configuração única, não há etapa manual de carimbo de tempo.

Configuração Única: Implantando o Timestamp GIT com Docker

A implantação é uma única pilha Docker Compose com dois serviços: a aplicação Timestamp GIT e uma instância Valkey usada como fila de hashes.

Crie um arquivo docker-compose.yml com a configuração exata da documentação do produto:

services:
  timestampgit:
    image: rue1401/timestampgit:prod
    ports:
      - "8080:8080"
    volumes:
      - ./data:/app/data
      - ./license.lic:/app/license.lic:ro
    restart: unless-stopped
  valkey:
    image: valkey/valkey:8
    restart: unless-stopped

Em seguida, execute:

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. No primeiro lançamento, um assistente de configuração orienta você na conexão do seu GitHub App e na configuração da sua instância. É aqui que você conclui a integração única. Você não instala nada nas máquinas dos desenvolvedores e não repete etapas manuais de carimbo de tempo depois.

Você precisa de um arquivo de licença montado em ./license.lic. Uma licença de demonstração com tempo limitado está disponível preenchendo o formulário de solicitação na página de Licença Docker com seu nome, empresa, e-mail e telefone opcional. Para uso em produção, use uma licença comercial.

Após a conclusão do assistente, o processo contínuo de carimbo de tempo é totalmente automatizado.

O Pipeline Automatizado: Do Commit à Âncora Bitcoin

Uma vez implantada, a instância auto-hospedada executa o mesmo fluxo de trabalho de configuração zero do serviço gerenciado Timestamp GIT.

Detecção de commits

Existem dois modos de detecção:

• Modo Padrão (GitHub App): O GitHub App detecta novos commits via webhooks. Ele lê apenas o hash do commit HEAD de cada repositório monitorado e envia esse hash para sua instância auto-hospedada.
• Modo Enterprise ZK: Uma GitHub Action de 12 linhas roda na sua infraestrutura e envia apenas o hash do commit para a API do Timestamp GIT. Nesse modo, o código-fonte nunca sai do seu ambiente, e a instância do Timestamp GIT não precisa de acesso de leitura ao repositório de origem.

Fila de hashes e agrupamento noturno

Os hashes de commit recebidos são armazenados na fila apoiada pelo Valkey. A cada noite, um worker cron dentro do contêiner do Timestamp GIT:

1. Agrupa todos os hashes pendentes de cada repositório.
2. Cria um arquivo de manifesto diário (.txt) para cada repositório.
3. Constrói uma árvore Merkle nativamente.
4. Cria provas OpenTimestamps usando calendários OTS públicos.
5. Ancora a raiz Merkle na blockchain do Bitcoin.

Entrega de provas

O manifesto e os arquivos de recibo .ots são enviados de volta para um branch dedicado de timestamps ou um repositório sombra, dependendo de como você configurou o GitHub App. Isso acontece automaticamente após a confirmação da âncora Bitcoin.

A confirmação do Bitcoin normalmente leva algumas horas, então as provas não aparecem instantaneamente após a meia-noite. Se você fizer commit às 15:00, esse hash é coletado na próxima execução noturna e normalmente é ancorado e entregue algumas horas depois.

Monitoramento e Tratamento de Falhas

Você pode monitorar o status de ancoragem diretamente através dos endpoints da API expostos pela sua instância auto-hospedada.

Endpoints de status

Para qualquer repositório público, você pode consultar:

curl https://timestampgit.example.com/api/statusLast/acme/checkout-service

Isso retorna JSON com as informações do último bloco Bitcoin ancorado.

curl https://timestampgit.example.com/api/statusCount/acme/checkout-service

Isso retorna a contagem total de commits realizados e carimbados.

curl https://timestampgit.example.com/api/statusSummary/acme/checkout-service

Isso retorna um resumo combinado adequado para selos Shields.io.

Repositórios privados anexam um HMAC criptografado à URL, para que apenas usuários autorizados possam visualizar seu status. O HMAC é específico da sua instância de servidor auto-hospedada.

Painel público

Cada repositório também tem um painel de status público em:

https://timestampgit.example.com/status/{user}/{repo}

Esta página mostra a longevidade da prova, a data da âncora mais antiga, a regularidade diária, dados de blocos e transações Bitcoin, um mapa de calor de calendário, um CSV de auditoria para download e um certificado em PDF.

Cenários de falha

• Se o worker cron falhar, verifique os logs do contêiner:

docker compose logs -f timestampgit

• Se a rede Bitcoin atrasar a confirmação, os endpoints de status ainda não mostrarão uma nova âncora. Isso geralmente é temporário.
• A instância auto-hospedada armazena seus dados no volume ./data. Reiniciar ou recriar os contêineres não perde hashes enfileirados nem a configuração.
• Configure alertas com base na API de status ou na saída de logs. Uma verificação diária de /api/statusLast é suficiente para a maioria das equipes. Se a data da última âncora parar de avançar, investigue o contêiner e o acesso de rede de saída.

Boas Práticas para Carimbo de Tempo Git Auto-Hospedado

• Restrinja o acesso à rede ao host Docker. Use regras de firewall e proxies reversos. Exponha apenas as portas que precisam ser acessíveis pelos webhooks do GitHub ou pela sua rede interna.
• Faça backup do volume ./data e do arquivo license.lic. O volume contém hashes enfileirados e a configuração da instância. O arquivo de licença deve permanecer legível pelo contêiner.
• Use um GitHub App dedicado com permissões mínimas. No Modo Padrão, o app precisa de acesso somente leitura aos repositórios de origem e acesso de leitura e gravação ao repositório de destino onde as provas são armazenadas. O Modo Enterprise ZK requer acesso de leitura e gravação apenas ao repositório de destino.
• Prefira um repositório sombra para as provas. Isso mantém seu repositório principal limpo e separa o histórico de origem dos recibos de carimbo de tempo.
• Verifique os carimbos de tempo regularmente. Use a página de verificação pública ou a API para confirmar que os recibos .ots ainda verificam contra os dados de blocos Bitcoin. Isso é especialmente importante antes de um evento legal ou de conformidade.
• Atualize as imagens dos contêineres deliberadamente. Use docker compose pull em uma janela de manutenção e verifique a nova versão em uma instância de staging antes de implantar em produção.

Perguntas Frequentes

P: Posso executar o Timestamp GIT em um ambiente completamente isolado?

R: Sim, a versão Docker auto-hospedada foi projetada para segurança máxima e pode rodar em ambientes isolados. No entanto, ela ainda precisa ancorar na blockchain do Bitcoin, então a instância deve ter acesso à internet de saída para alcançar nós Bitcoin ou calendários OpenTimestamps. Se o isolamento total for necessário, você pode precisar de um proxy ou relay para a etapa de ancoragem.

P: Como obtenho uma licença para a versão Docker auto-hospedada?

R: Você pode solicitar uma licença de demonstração com tempo limitado preenchendo o formulário na página de Licença Docker com seu nome, empresa, e-mail e telefone opcional. Um arquivo de licença será fornecido para avaliação. Para uso em produção, entre em contato com o fornecedor para obter uma licença comercial.

P: A versão auto-hospedada requer um GitHub App?

R: Sim, a instância auto-hospedada do Timestamp GIT ainda usa um GitHub App para detectar commits e enviar provas de volta aos seus repositórios. Durante o assistente de configuração, você conectará as credenciais do seu GitHub App. O app requer acesso somente leitura aos repositórios de origem e acesso de leitura e gravação ao repositório de destino onde as provas são armazenadas.

P: Quais são os requisitos de recursos para executar o Timestamp GIT com Docker?

R: As informações do produto não especificam requisitos exatos de recursos, mas o Docker Compose inclui dois serviços: a aplicação Timestamp GIT e uma instância Valkey (compatível com Redis) para a fila de hashes. Para equipes pequenas e médias, um VPS modesto com 1-2 GB de RAM deve ser suficiente. Monitore o uso de recursos e escale conforme necessário.

Conclusão

O carimbo de tempo Git auto-hospedado com Docker remove o trabalho manual repetitivo da proteção de estado da técnica. Você implanta a pilha uma vez, conecta o GitHub App, e cada commit em um repositório monitorado flui por um pipeline automatizado: detecção de hash, agrupamento noturno, criação de prova Merkle, ancoragem em Bitcoin e entrega de prova de volta ao seu repositório.

Essa é a diferença entre uma salvaguarda legal que você realmente usa e uma que se torna uma tarefa árdua. Se você está pronto para implantar, comece com a pilha Docker Compose acima e solicite uma licença de demonstração na página de Licença Docker. Para equipes que preferem não operar sua própria instância, o serviço gerenciado Timestamp GIT oferece a mesma automação sem auto-hospedagem.

Posts relacionados

• Como Carimbar Criptograficamente Commits Git (Sem Ferramentas de CLI)
• Preços do Timestamp GIT: Planos para Cada Desenvolvedor
• Prova de Existência em Software: Um Guia para Iniciantes