Sellado de tiempo de Git autohospedado con Docker: una guía

La tarea manual repetitiva que vas a eliminar es esta: cada vez que quieres una prueba criptográficamente defendible de que un commit de Git existió en una fecha determinada, o ejecutas comandos de sellado de tiempo a mano o envías metadatos a un servicio que no controlas por completo. Para startups, estudios de desarrollo y equipos con mentalidad de cumplimiento, eso crea una brecha. Los pasos manuales se omiten. Las dependencias externas plantean cuestiones de soberanía de datos. Los entornos regulados o aislados a menudo no pueden usar un SaaS gestionado en absoluto.

La forma difícil es ejecutar OpenTimestamps tú mismo y vigilar cada recibo. La forma práctica es desplegar Timestamp GIT como una aplicación Docker autohospedada: la misma automatización basada en GitHub App, el anclaje nocturno en Bitcoin y las insignias de verificación se ejecutan en infraestructura de tu propiedad.

Si necesitas un repaso sobre por qué la prueba de existencia importa en el software antes de continuar, consulta Prueba de existencia en el software: una guía para principiantes.

¿Por qué autohospedar el sellado de tiempo de Git?

Autohospedar Timestamp GIT no se trata de evitar el servicio gestionado. Se trata de ejecutar la misma automatización detrás de tu propio firewall, con tu propio volumen de datos, tu propia licencia y tus propias reglas de red. Eso importa cuando:

• Necesitas soberanía de datos y no quieres que los metadatos de commits salgan de tu entorno más allá del paso de anclaje en Bitcoin.
• Operas en un entorno regulado o aislado donde las conexiones a SaaS de terceros están restringidas.
• Quieres control total sobre las credenciales de la GitHub App, la ubicación de almacenamiento y el acceso a los registros.
• Necesitas un despliegue apto para auditorías que permanezca bajo el control operativo de tu equipo.

La opción Docker autohospedada te ofrece el mismo pipeline automatizado: instala la GitHub App una vez, conecta repositorios y deja que la instancia agrupe los hashes de commits cada noche, construya pruebas de Merkle y las ancle en Bitcoin. Después de la configuración única, no hay ningún paso manual de sellado de tiempo.

Configuración única: despliegue de Timestamp GIT con Docker

El despliegue es una única pila de Docker Compose con dos servicios: la aplicación Timestamp GIT y una instancia de Valkey utilizada como cola de hashes.

Crea un archivo docker-compose.yml con la configuración exacta de la documentación del producto:

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

Luego ejecuta:

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

La aplicación está disponible en http://localhost:8080 después del arranque. En el primer lanzamiento, un asistente de configuración te guía para conectar tu GitHub App y configurar tu instancia. Aquí es donde completas la integración única. No instalas nada en las máquinas de los desarrolladores y no repites pasos manuales de sellado de tiempo más adelante.

Necesitas un archivo de licencia montado en ./license.lic. Hay una licencia de demostración por tiempo limitado disponible rellenando el formulario de solicitud en la página de licencia Docker con tu nombre, empresa, correo electrónico y número de teléfono opcional. Para uso en producción, utiliza una licencia comercial.

Una vez completado el asistente, el proceso de sellado de tiempo continuo está totalmente automatizado.

El pipeline automatizado: del commit al anclaje en Bitcoin

Una vez desplegada, la instancia autohospedada ejecuta el mismo flujo de trabajo de configuración cero que el servicio gestionado de Timestamp GIT.

Detección de commits

Hay dos modos de detección:

• Modo estándar (GitHub App): La GitHub App detecta nuevos commits mediante webhooks. Lee solo el hash del commit HEAD de cada repositorio monitorizado y envía ese hash a tu instancia autohospedada.
• 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 de Timestamp GIT. En este modo, el código fuente nunca sale de tu entorno y la instancia de Timestamp GIT no necesita acceso de lectura al repositorio de origen.

Cola de hashes y agrupación nocturna

Los hashes de commits entrantes se almacenan en la cola respaldada por Valkey. Cada noche, un trabajador cron dentro del contenedor de Timestamp GIT:

1. Agrupa todos los hashes pendientes de cada repositorio.
2. Crea un archivo de manifiesto diario (.txt) para cada repositorio.
3. Construye un árbol de Merkle de forma nativa.
4. Crea pruebas de OpenTimestamps utilizando calendarios OTS públicos.
5. Ancla la raíz de Merkle en la blockchain de Bitcoin.

Entrega de pruebas

El manifiesto y los archivos de recibo .ots se envían de vuelta a una rama de timestamps dedicada o a un repositorio sombra, dependiendo de cómo configuraste la GitHub App. Esto ocurre automáticamente después de que el anclaje en Bitcoin se confirme.

La confirmación en Bitcoin normalmente tarda unas horas, por lo que las pruebas no aparecen instantáneamente después de la medianoche. Si haces un commit a las 15:00, ese hash se recoge en la siguiente ejecución nocturna y normalmente se ancla y entrega unas horas más tarde.

Monitorización y manejo de fallos

Puedes monitorizar el estado del anclaje directamente a través de los endpoints de la API expuestos por tu instancia autohospedada.

Endpoints de estado

Para cualquier repositorio público, puedes consultar:

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

Esto devuelve JSON con la información del último bloque de Bitcoin anclado.

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

Esto devuelve el recuento total de commits realizados y sellados.

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

Esto devuelve un resumen combinado adecuado para insignias de Shields.io.

Los repositorios privados añaden un HMAC cifrado a la URL, de modo que solo los usuarios autorizados pueden ver su estado. El HMAC es específico de tu instancia de servidor autohospedada.

Panel público

Cada repositorio también tiene un panel de estado público en:

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

Esta página muestra la longevidad de las pruebas, la fecha de anclaje más antigua, la regularidad diaria, los datos de bloques y transacciones de Bitcoin, un mapa de calor de calendario, un CSV de auditoría descargable y un certificado en PDF.

Escenarios de fallo

• Si el trabajador cron falla, revisa los registros del contenedor:

docker compose logs -f timestampgit

• Si la red de Bitcoin retrasa la confirmación, los endpoints de estado aún no mostrarán un nuevo anclaje. Esto suele ser temporal.
• La instancia autohospedada almacena sus datos en el volumen ./data. Reiniciar o recrear los contenedores no pierde los hashes en cola ni la configuración.
• Configura alertas basadas en la API de estado o en la salida de los registros. Una comprobación diaria de /api/statusLast es suficiente para la mayoría de los equipos. Si la fecha del último anclaje deja de avanzar, investiga el contenedor y el acceso de red saliente.

Buenas prácticas para el sellado de tiempo de Git autohospedado

• Restringe el acceso de red al host Docker. Usa reglas de firewall y proxies inversos. Expón solo los puertos que necesitan ser alcanzables por los webhooks de GitHub o tu red interna.
• Haz copias de seguridad del volumen ./data y del archivo license.lic. El volumen contiene los hashes en cola y la configuración de la instancia. El archivo de licencia debe permanecer legible por el contenedor.
• Usa una GitHub App dedicada con permisos mínimos. En el modo estándar, la app necesita acceso de solo lectura a los repositorios de origen y acceso de lectura-escritura al repositorio de destino donde se almacenan las pruebas. El modo Enterprise ZK requiere acceso de lectura-escritura solo al repositorio de destino.
• Prefiere un repositorio sombra para las pruebas. Esto mantiene tu repositorio principal limpio y separa el historial de código fuente de los recibos de sellado de tiempo.
• Verifica regularmente los sellados de tiempo. Usa la página de verificación pública o la API para confirmar que los recibos .ots siguen verificándose contra los datos de bloques de Bitcoin. Esto es especialmente importante antes de un evento legal o de cumplimiento.
• Actualiza las imágenes de los contenedores de forma deliberada. Usa docker compose pull en una ventana de mantenimiento y verifica la nueva versión contra una instancia de staging antes de pasar a producción.

Preguntas frecuentes

P: ¿Puedo ejecutar Timestamp GIT en un entorno completamente aislado?

R: Sí, la versión Docker autohospedada está diseñada para máxima seguridad y puede ejecutarse en entornos aislados. Sin embargo, aún necesita anclar a la blockchain de Bitcoin, por lo que la instancia debe tener acceso saliente a internet para alcanzar los nodos de Bitcoin o los calendarios de OpenTimestamps. Si se requiere un aislamiento total, es posible que necesites un proxy o relay para el paso de anclaje.

P: ¿Cómo obtengo una licencia para la versión Docker autohospedada?

R: Puedes solicitar una licencia de demostración por tiempo limitado rellenando el formulario de la página de licencia Docker con tu nombre, empresa, correo electrónico y número de teléfono opcional. Se te proporcionará un archivo de licencia para evaluación. Para uso en producción, contacta con el proveedor para obtener una licencia comercial.

P: ¿La versión autohospedada requiere una GitHub App?

R: Sí, la instancia autohospedada de Timestamp GIT sigue utilizando una GitHub App para detectar commits y enviar las pruebas de vuelta a tus repositorios. Durante el asistente de configuración, conectarás las credenciales de tu GitHub App. La app requiere acceso de solo lectura a los repositorios de origen y acceso de lectura-escritura al repositorio de destino donde se almacenan las pruebas.

P: ¿Cuáles son los requisitos de recursos para ejecutar Timestamp GIT con Docker?

R: La información del producto no especifica requisitos de recursos exactos, pero el Docker Compose incluye dos servicios: la aplicación Timestamp GIT y una instancia de Valkey (compatible con Redis) para la cola de hashes. Para equipos pequeños y medianos, un VPS modesto con 1-2 GB de RAM debería ser suficiente. Monitoriza el uso de recursos y escala según sea necesario.

Conclusión

El sellado de tiempo de Git autohospedado con Docker elimina el trabajo manual tedioso de la protección del estado de la técnica. Despliegas la pila una vez, conectas la GitHub App y cada commit a un repositorio monitorizado fluye a través de un pipeline automatizado: detección de hashes, agrupación nocturna, creación de pruebas de Merkle, anclaje en Bitcoin y entrega de pruebas de vuelta a tu repositorio.

Esa es la diferencia entre una salvaguarda legal que realmente usas y una que se convierte en una carga. Si estás listo para desplegar, comienza con la pila de Docker Compose anterior y solicita una licencia de demostración en la página de licencia Docker. Para equipos que prefieren no operar su propia instancia, el servicio gestionado de Timestamp GIT ofrece la misma automatización sin autohospedaje.

Publicaciones relacionadas

• Cómo sellar criptográficamente commits de Git (sin herramientas de CLI)
• Precios de Timestamp GIT: planes para cada desarrollador
• Prueba de existencia en el software: una guía para principiantes