Timestamp GIT

← Todos los artículos

2026-11-13

Autoalojamiento de sellado de tiempo Git con Docker Compose

Autoalojamiento de sellado de tiempo Git con Docker Compose
timestamp git blockchain proof

Autoalojamiento de la marca de tiempo de Git con Docker Compose

La marca de tiempo manual falla siempre de la misma manera. Alguien escribe un runbook, otra persona lo convierte en un script, el script se ejecuta durante tres semanas, un disco se llena o un token caduca, y nadie se da cuenta hasta el día en que un abogado pide pruebas de que tu repositorio tenía un aspecto determinado hace dieciocho meses.

El anclaje en sí no es la parte difícil. La parte difícil es el pipeline que lo rodea: detectar commits, agrupar hashes, sobrevivir a los reinicios, entregar los recibos y mantener todo verificable años después. Eso es exactamente lo que te aporta un stack de Compose autoalojado: un despliegue repetible e inspeccionable en el que la automatización se ejecuta en tu red y tú eres el dueño del directorio de datos.

Este artículo explica cómo desplegar Timestamp GIT on-premises con Docker Compose, conectar una GitHub App una sola vez y dejar que un worker nocturno automatizado ancle tus hashes de commit en Bitcoin. Si primero quieres el contexto conceptual, lee Cryptographic Prior Art: The Startup Shield Against Patent Trolls.

¿Por qué autoalojar la marca de tiempo de Git?

Ejecutar un paso de marca de tiempo a mano significa recordar tres tareas por repositorio: conseguir que se sellen los hashes de commit, recopilar los archivos de prueba resultantes y almacenarlos en algún lugar duradero y auditable. Si te saltas una, la cadena tiene huecos; si te saltas el paso de almacenamiento, tienes recibos que nadie puede localizar.

El autoalojamiento cubre una clase distinta de requisitos:

  • Residencia de datos. Los equipos de cumplimiento quieren saber dónde se procesan los metadatos de commit. Con la imagen de Docker, la respuesta es “en nuestro host”.
  • Redes restringidas. Algunos equipos no concederán a ningún SaaS acceso de lectura a los repositorios de código fuente, ni siquiera de solo lectura, independientemente de lo que prometa un proveedor.
  • Despliegues próximos a air-gapped. Puedes ejecutar la imagen en un host interno; solo el paso de anclaje necesita acceso saliente a los calendarios públicos de OpenTimestamps.
  • Control operativo. Tú decides la cadencia de actualización, el calendario de copias de seguridad y quién puede acceder al asistente de configuración.

Docker Compose encaja bien porque todo el sistema son dos contenedores: la aplicación y una instancia de Valkey usada como cola de hashes en memoria. Un pull y un up -d te dan una instancia en funcionamiento; el volumen ./data conserva el estado entre reinicios; actualizar es docker compose pull && docker compose up -d.

Fundamentalmente, la imagen de Docker es la misma automatización que el producto alojado —detección de commits impulsada por la GitHub App, anclaje nocturno en Bitcoin, recibos .ots enviados de vuelta a tu repositorio—, solo que ejecutándose en tu infraestructura.

Configuración única: Docker Compose y GitHub App

Requisitos previos

  • Docker Engine con el plugin de Compose.
  • Un host con un tiempo de actividad fiable y acceso a internet saliente (necesario para el anclaje en Bitcoin mediante los calendarios públicos de OpenTimestamps).
  • Una GitHub App que puedas instalar en los repositorios de destino, y un repositorio de destino (o repositorio en la sombra) donde se puedan escribir las ramas de prueba.
  • Un archivo de licencia para la instancia.

El archivo Compose

Una configuración rápida de Docker Compose tiene este aspecto:

services:
  timestampgit:
    image: rue1401/timestampgit:prod
    ports:
      - "8080:8080"
    volumes:
      - ./data:/app/data
    restart: unless-stopped

  valkey:
    image: valkey/valkey:8
    restart: unless-stopped

Hay dos cosas que debes tener en cuenta antes de continuar. El bind mount ./data:/app/data es el estado duradero de la instancia: trátalo como datos críticos, no como una caché. Y restart: unless-stopped importa más de lo habitual aquí: el worker de medianoche tiene que estar vivo a medianoche.

Inicia el stack:

docker compose pull
docker compose up -d
docker compose logs -f timestampgit

La aplicación está disponible en http://localhost:8080 tras el arranque.

Primer arranque

En el primer arranque, un asistente de configuración te guía para conectar tu GitHub App y configurar tu instancia. Planifica los permisos antes de ir haciendo clic:

  • Modo estándar. La GitHub App solo lee el hash del commit HEAD de cada repositorio monitorizado y escribe las pruebas en un repositorio de destino. El modelo de permisos de GitHub exige al menos acceso de solo lectura al repositorio de origen, además de acceso de lectura y escritura al de destino.
  • Modo Enterprise ZK. Una GitHub Action de 12 líneas se ejecuta en tu infraestructura y envía solo el hash del commit a la API. Necesitas acceso de lectura y escritura al repositorio de destino y ningún acceso de lectura al de origen.

Si estás evaluando esto en 2026 para un equipo que ya se ha estandarizado con el flujo de trabajo de la GitHub App alojada, los pasos de configuración te resultarán familiares; consulta Automate Git Commit Timestamping With a GitHub App para esa vía.

Licencias

Hay disponible una licencia de demostración por tiempo limitado para evaluación enviando el formulario de solicitud de la página Docker License con tu nombre, empresa, correo electrónico y número de teléfono opcional. Puedes descargar un archivo de licencia de demostración por tiempo limitado y subirlo durante la configuración de Enterprise.

Si se puede acceder a la instancia desde cualquier lugar que no sea localhost, colócala detrás de un proxy inverso que termine TLS y restringe el acceso en la capa de red. El asistente de configuración es una superficie administrativa.

El pipeline automatizado: del commit a la prueba en Bitcoin

Una vez conectada la GitHub App, el pipeline se ejecuta por sí solo:

  1. Detección de commits. La GitHub App recibe webhooks de nuevos commits o, en el modo Enterprise ZK, tu GitHub Action envía los hashes de commit a la API.
  2. Cola de hashes. Los hashes de commit llegan a Valkey, el almacén clave-valor en memoria usado para el agrupamiento.
  3. Worker cron de medianoche. Cada noche el worker agrupa todos los hashes pendientes, escribe un manifiesto .txt por repositorio, construye un árbol de Merkle, crea pruebas de OpenTimestamps usando los calendarios públicos de OTS y ancla la raíz de Merkle en Bitcoin.
  4. Entrega de pruebas. El manifiesto y los archivos de recibo .ots se envían de vuelta a tu repositorio en una rama dedicada de marcas de tiempo o en un repositorio en la sombra.
  5. Confirmación. La confirmación en Bitcoin tarda varias horas —normalmente unas tres—, así que la escritura de las pruebas se completa unas horas después de que se ejecute el lote.

La propiedad de conocimiento cero es estructural, no una declaración de políticas: solo se procesan hashes de commit. Tanto si ejecutas el modo estándar como el modo Enterprise ZK, tu código fuente nunca sale de tu red. El despliegue con Docker simplemente traslada también el paso de procesamiento de hashes dentro de tu perímetro.

Como la raíz de Merkle se ancla en un bloque de Bitcoin mediante OpenTimestamps, la marca de tiempo se vuelve inmutable una vez confirmada. Ninguna entidad puede alterarla ni falsificarla, incluidos el proveedor y tú mismo.

Monitorización y gestión de fallos

Un pipeline de marcas de tiempo falla en silencio. Los hashes de commit se acumulan en la cola, no se produce ningún error y descubres el hueco durante una auditoría. Trata la monitorización como parte del despliegue.

Salud del contenedor y de la cola. La comprobación más útil es el propio estado de la aplicación para un repositorio conocido. Apunta tu monitor de disponibilidad a él:

#!/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} devuelve la información del último bloque de Bitcoin anclado. Si ese bloque deja de avanzar, el worker está atascado.

Insignias de verificación públicas. Para cada repositorio monitorizado, el widget de insignia genera markdown de Shields.io incrustable para tu README. El fragmento lo sirve GET /api/badgeLink/{user}/{repo} (autenticado) y tiene un aspecto similar a este:

[![Timestamped in Bitcoin](https://img.shields.io/endpoint?url=https://timestampgit.dev/api/statusSummary/acme/platform)](https://timestampgit.dev/status/acme/platform)

Cualquiera puede seguir el enlace para verificar la marca de tiempo a través del sitio web. Para repositorios privados, la URL de estado lleva un HMAC cifrado específico de la instancia de tu servidor, de modo que solo los usuarios autorizados pueden leer el estado.

Auditoría e informes. Extrae el registro de forma programada en lugar de bajo 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)"

Así obtienes un registro de auditoría en CSV y un certificado PDF por fecha que los equipos legal y de cumplimiento pueden archivar sin tocar ellos mismos la API.

Retrasos en la confirmación. El anclaje normalmente se resuelve en unas tres horas. Los retrasos ocurren; el worker reintenta y entrega la prueba .ots una vez confirmado el anclaje. Configura alertas para “manifiesto escrito pero sin recibo tras 24 horas” en lugar de para retrasos cortos; de lo contrario, te avisarán por la variación normal de los bloques de Bitcoin.

Copia de seguridad y restauración. Haz copias de seguridad de ./data de forma programada y monta un volumen con nombre para el directorio /data de Valkey si quieres que los hashes en cola sobrevivan a la recreación de un contenedor. Valkey es un almacén en memoria por diseño: perderlo te cuesta el lote de una noche, no tus pruebas existentes, porque las pruebas entregadas viven en la rama de marcas de tiempo.

Buenas prácticas para la marca de tiempo autoalojada

  • Dedica un host. El worker se ejecuta a medianoche y necesita un tiempo de actividad estable y conectividad saliente. Compartir host con una granja de compilación ruidosa es pedir que se pierda un lote.
  • Mantén el volumen de datos fuera del almacenamiento efímero. Haz un bind mount de ./data a un disco duradero e inclúyelo en tu rotación de copias de seguridad.
  • Restringe la superficie de administración. Coloca el asistente y la API autenticada detrás de tu VPN o proxy inverso con autenticación fuerte. No expongas el puerto 8080 a internet público.
  • Actualiza de forma deliberada. Ejecuta docker compose pull según un calendario que tú controles; lee el changelog antes de descargar una nueva imagen :prod.
  • Prefiere el modo Enterprise ZK cuando los permisos estén en disputa. Si tu equipo de seguridad no concede acceso de lectura a los repositorios de origen, la vía de la GitHub Action los satisface sin cambiar la automatización.
  • Documenta el proceso para los auditores. Deja por escrito dónde se ejecuta la instancia, quién la administra, cómo se verifican las copias de seguridad y dónde se almacenan los recibos .ots. La prueba es criptográfica; la cadena de custodia aún necesita un párrafo.
  • Prueba una verificación de principio a fin. Elige una fecha anclada y recorre el flujo de verificación antes de necesitarlo en una disputa, no durante una. Para el marco legal, consulta Is a Bitcoin Timestamp Admissible as Evidence? A Compliance Guide.

Preguntas frecuentes

¿Necesito exponer mi código fuente a Timestamp GIT? No. Timestamp GIT solo procesa hashes de commit. En el modo estándar, la GitHub App lee el hash del commit HEAD; en el modo Enterprise ZK, una GitHub Action envía solo el hash desde tu infraestructura. Tu código fuente nunca sale de tu red.

¿Qué ocurre si la confirmación en Bitcoin tarda más de lo esperado? El worker cron de medianoche ancla la raíz de Merkle en Bitcoin mediante OpenTimestamps. La confirmación suele tardar unas 3 horas. Si la confirmación se retrasa, el worker reintentará y entregará la prueba .ots una vez confirmada.

¿Puedo usar esto en un entorno air-gapped? Sí, la imagen de Docker puede ejecutarse en un entorno air-gapped, pero se requiere acceso a internet saliente para el anclaje en Bitcoin mediante los calendarios públicos de OpenTimestamps. Puedes configurar el acceso de red en consecuencia.

¿Cómo verifico una marca de tiempo de forma independiente? Puedes descargar el archivo .ots y verificarlo con las herramientas de verificación estándar de OpenTimestamps contra la cadena de bloques de Bitcoin. Como alternativa, usa la página de verificación que ofrece Timestamp GIT, que realiza la verificación local en tu navegador: nadie ve lo que verificas.

Conclusión

Autoalojar la marca de tiempo de Git no va de desconfiar de un proveedor; va de poner un pipeline automatizado y auditable dentro de un límite que tu equipo de cumplimiento ya acepta. Dos contenedores, un archivo de licencia, una GitHub App, y a partir de ahí el worker de medianoche hace la parte repetitiva mientras tú obtienes un repositorio lleno de recibos .ots y una página de estado pública.

Empieza solicitando una licencia de demostración en la página Docker License, levanta el stack de Compose en un host de staging y verifica un día anclado de principio a fin. Si prefieres saltarte la infraestructura, la GitHub App gestionada Timestamp GIT te ofrece el mismo anclaje nocturno sin configuración, y puedes migrar a autoalojado más adelante sin cambiar lo que llega a tu repositorio.

Entradas relacionadas

EU label: AI-generated content