Self-Host Git Timestamping With Docker Compose
Manual timestamping fails the same way every time. Someone writes a runbook, someone else turns it into a script, the script runs for three weeks, a disk fills up or a token expires, and nobody notices until the day a lawyer asks for proof that your repository looked a certain way eighteen months ago.
The anchoring itself is not the hard part. The hard part is the pipeline around it: detecting commits, batching hashes, surviving restarts, delivering receipts, and keeping the whole thing verifiable years later. That is exactly what a self-hosted Compose stack buys you — a repeatable, inspectable deployment where the automation runs on your network and you own the data directory.
This article walks through deploying Timestamp GIT on-premises with Docker Compose, connecting a GitHub App once, and letting an automated nightly worker anchor your commit hashes into Bitcoin. If you want the conceptual background first, read Cryptographic Prior Art: The Startup Shield Against Patent Trolls.
Why Self-Host Git Timestamping?
Running a timestamping step by hand means remembering three chores per repository: getting the commit hashes stamped, collecting the resulting proof files, and storing them somewhere durable and auditable. Miss one and the chain has holes; miss the storage step and you have receipts nobody can locate.
Self-hosting addresses a different class of requirements:
- Data residency. Compliance teams want to know where commit metadata is processed. With the Docker image, the answer is “on our host”.
- Restricted networks. Some teams will not grant any SaaS read access to source repositories — even read-only — regardless of what a vendor promises.
- Air-gapped-adjacent deployments. You can run the image on an internal host; only the anchoring step needs outbound access to public OpenTimestamps calendars.
- Operational control. You decide the update cadence, the backup schedule, and who can reach the setup wizard.
Docker Compose is a good fit because the whole system is two containers: the application and a Valkey instance used as the in-memory hash queue. One pull and one up -d gets you a running instance; the ./data volume keeps state across restarts; updating is docker compose pull && docker compose up -d.
Critically, the Docker image is the same automation as the hosted product — GitHub App-driven commit detection, nightly Bitcoin anchoring, .ots receipts pushed back to your repository — just running on your infrastructure.
One-Time Setup: Docker Compose and GitHub App
Prerequisites
- Docker Engine with the Compose plugin.
- A host with reliable uptime and outbound internet access (required for Bitcoin anchoring via public OpenTimestamps calendars).
- A GitHub App you can install on the target repositories, and a target repository (or shadow repository) where proof branches can be written.
- A license file for the instance.
The Compose file
A quick-start Docker Compose setup looks like this:
services:
timestampgit:
image: rue1401/timestampgit:prod
ports:
- "8080:8080"
volumes:
- ./data:/app/data
restart: unless-stopped
valkey:
image: valkey/valkey:8
restart: unless-stopped
Two things to note before you go further. The ./data:/app/data bind mount is the durable state of the instance — treat it as critical data, not as a cache. And restart: unless-stopped matters more than it usually does here: the midnight worker has to be alive at midnight.
Start the stack:
docker compose pull
docker compose up -d
docker compose logs -f timestampgit
The application is available at http://localhost:8080 after startup.
First launch
On first launch, a setup wizard guides you through connecting your GitHub App and configuring your instance. Plan the permissions before you click through:
- Standard Mode. The GitHub App reads only the HEAD commit hash of each monitored repository, and writes proofs to a target repository. GitHub’s permission model requires at least read-only access to the source repository, plus read-write access to the target.
- Enterprise ZK Mode. A 12-line GitHub Action runs on your infrastructure and pushes only the commit hash to the API. You need read-write access to the target repository and no read access to the source.
If you are evaluating this in 2026 for a team that has already standardized on the hosted GitHub App workflow, the setup steps will feel familiar — see Automate Git Commit Timestamping With a GitHub App for that path.
Licensing
A time-limited demo license for evaluation is available by submitting the request form on the Docker License page with your name, company, email, and optional phone number. You can download a time-limited demo license file and upload it during Enterprise setup.
If the instance is reachable from anywhere other than localhost, put it behind a TLS-terminating reverse proxy and restrict access at the network layer. The setup wizard is an administrative surface.
The Automated Pipeline: From Commit to Bitcoin Proof
Once the GitHub App is connected, the pipeline runs on its own:
- Commit detection. The GitHub App receives webhooks for new commits, or — in Enterprise ZK Mode — your GitHub Action pushes commit hashes to the API.
- Hash queue. Commit hashes land in Valkey, the in-memory key-value store used for batching.
- Midnight cron worker. Each night the worker groups all pending hashes, writes a manifest
.txtper repository, builds a Merkle tree, creates OpenTimestamps proofs using public OTS calendars, and anchors the Merkle root into Bitcoin. - Proof delivery. The manifest and
.otsreceipt files are pushed back to your repository in a dedicated timestamps branch or a shadow repository. - Confirmation. Bitcoin confirmation takes several hours — normally around three — so proof writing completes a few hours after the batch runs.
The zero-knowledge property is structural, not a policy statement: only commit hashes are processed. Whether you run Standard Mode or Enterprise ZK Mode, your source code never leaves your network. The Docker deployment simply moves the hash-processing step inside your perimeter too.
Because the Merkle root is anchored in a Bitcoin block via OpenTimestamps, the timestamp becomes immutable once confirmed. No entity can alter or forge it — including the vendor, and including you.
Monitoring and Failure Handling
A timestamping pipeline fails quietly. Commit hashes queue up, nothing errors, and you discover the gap during an audit. Treat monitoring as part of the deployment.
Container and queue health. The most useful check is the application’s own status for a known repository. Point your uptime monitor at it:
#!/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} returns the last anchored Bitcoin block info. If that block stops advancing, the worker is stuck.
Public verification badges. For each monitored repository, the badge widget produces embeddable Shields.io markdown for your README. The snippet is served by GET /api/badgeLink/{user}/{repo} (authenticated), and looks roughly like:
[](https://timestampgit.dev/status/acme/platform)
Anyone can follow the link to verify the timestamp through the website. For private repositories, the status URL carries an encrypted HMAC specific to your server instance, so only authorized users can read the status.
Audit and reports. Pull the ledger on a schedule rather than on demand:
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)"
That gives you a CSV audit ledger and a per-date PDF certificate that legal and compliance teams can file without touching the API themselves.
Confirmation delays. Anchoring normally settles in about three hours. Delays happen; the worker retries and delivers the .ots proof once the anchor is confirmed. Alert on “manifest written but no receipt after 24 hours” rather than on short delays, otherwise you will page yourself over normal Bitcoin block variance.
Backup and restore. Back up ./data on a schedule, and mount a named volume for Valkey’s /data directory if you want queued hashes to survive a container recreation. Valkey is an in-memory store by design — losing it costs you a night’s batch, not your existing proofs, because delivered proofs live in the timestamps branch.
Best Practices for Self-Hosted Timestamping
- Dedicate a host. The worker runs at midnight and needs stable uptime and outbound connectivity. Sharing a host with a noisy build farm is asking for a missed batch.
- Keep the data volume out of ephemeral storage. Bind-mount
./datato durable disk and include it in your backup rotation. - Restrict the admin surface. Put the wizard and authenticated API behind your VPN or reverse proxy with strong authentication. Do not expose port 8080 to the public internet.
- Update deliberately.
docker compose pullon a schedule you control; read the changelog before pulling a new:prodimage. - Prefer Enterprise ZK Mode when permissions are contested. If your security team will not grant read access to source repositories, the GitHub Action path satisfies them without changing the automation.
- Document the process for auditors. Write down where the instance runs, who administers it, how backups are verified, and where
.otsreceipts are stored. The proof is cryptographic; the chain of custody still needs a paragraph. - Test one verification end to end. Pick an anchored date and walk the verification flow before you need it in a dispute, not during one. For the legal framing, see Is a Bitcoin Timestamp Admissible as Evidence? A Compliance Guide.
FAQ
Do I need to expose my source code to Timestamp GIT? No. Timestamp GIT only processes commit hashes. In Standard Mode, the GitHub App reads the HEAD commit hash; in Enterprise ZK Mode, a GitHub Action pushes only the hash from your infrastructure. Your source code never leaves your network.
What happens if the Bitcoin confirmation takes longer than expected?
The midnight cron worker anchors the Merkle root into Bitcoin via OpenTimestamps. Confirmation typically takes around 3 hours. If confirmation is delayed, the worker will retry and deliver the .ots proof once confirmed.
Can I use this in an air-gapped environment? Yes, the Docker image can run in an air-gapped environment, but outbound internet access is required for Bitcoin anchoring via public OpenTimestamps calendars. You can configure network access accordingly.
How do I verify a timestamp independently?
You can download the .ots file and verify it with standard OpenTimestamps verification tools against the Bitcoin blockchain. Alternatively, use the verification page provided by Timestamp GIT, which performs local verification in your browser — nobody sees what you verify.
Conclusion
Self-hosting git timestamping is not about distrust of a vendor; it is about putting an automated, auditable pipeline inside a boundary your compliance team already accepts. Two containers, one license file, one GitHub App — and after that the midnight worker does the repetitive part while you get a repository full of .ots receipts and a public status page.
Start by requesting a demo license on the Docker License page, bring up the Compose stack on a staging host, and verify one anchored day end to end. If you would rather skip the infrastructure, the managed Timestamp GIT GitHub App gives you the same nightly anchoring with zero setup — and you can migrate to self-hosted later without changing what lands in your repository.
Related posts
- 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