TruthGate is a self-hosted edge gateway, control plane, and static-site publishing system for Kubo/IPFS.
It packages the TruthGate web application, Kubo, and the matching ipfs CLI into one Docker appliance, then adds the operational layer that an internet-facing IPFS node usually needs: authenticated accounts, API keys, the native IPFS WebUI behind login, protected gateway and RPC routes, CID and IPNS pinning, domain routing, automatic TLS, static-site publishing, rate limiting, persistent storage, migrations, and diagnostics.
Read the documentation · Docker Hub · Report an issue
Kubo is the distributed content system. It addresses content, exchanges blocks, resolves IPNS, participates in the DHT, and exposes powerful local APIs.
Running a useful public service around Kubo still leaves an operator with a different set of problems:
- How do you administer the node without exposing Kubo's unrestricted RPC API to the internet?
- How do multiple people sign in with separate accounts?
- How do applications receive revocable API credentials?
- How do you use the familiar native IPFS WebUI remotely without opening it to everyone?
- How do you publish a static site, bind domains, route SPAs, and obtain certificates?
- How do you follow an IPNS name and keep its current CID pinned automatically?
- How do you update Kubo and TruthGate without losing the repository, identity, keys, database, certificates, or blocks?
- How do you protect public routes from obvious abuse while keeping real users and shared networks usable?
TruthGate sits at that boundary. Kubo remains responsible for IPFS. TruthGate provides the authenticated management plane, publishing workflows, HTTP edge behavior, and operational controls around it.
TruthGate has a login-protected management portal with role-based user accounts. The first boot creates an admin account with a unique generated password instead of a shared default credential. Additional users and password changes are managed from the portal.
Applications can use API keys rather than interactive sessions. Keys are shown once when created and stored as hashes. They can be revoked without changing a user's password.
TruthGate proxies the native IPFS WebUI through the authenticated portal. Operators keep the interface they already know for browsing files, creating folders, importing content, and managing pins, but the underlying Kubo gateway and RPC API stay bound to loopback inside the appliance.
TruthGate also exposes familiar routes such as /ipfs/, /ipns/, and the supported /api/v0/ proxy through its own TLS, authentication, API-key, and rate-protection layers.
Static CID pinning is built in, but watched IPNS pinning is one of TruthGate's most useful features.
An operator can subscribe to an IPNS name and let TruthGate resolve it on a schedule. When the name changes, TruthGate can pin the new target and apply the configured retention behavior to older targets. That turns a mutable IPNS identity into a continuously maintained local copy instead of a manual sequence of resolve-and-pin commands.
TruthGate supports the TruthGate Pointer protocol (TGP): a small structured layer in which an IPNS identity publishes a lightweight control bundle whose tgp.json points to the current immutable application CID.
TGP deliberately trades one additional resolution hop for a predictable machine-readable pointer, inexpensive freshness checks, normal immutable caching of the application, a browser-capable index.html fallback, and a stable place for future routing behavior. The public IPNS location can guide IPFS-aware browsers, ordinary browsers, and fallback routes without making the full application DAG serve as the control record.
IPNS can already move to a new CID, and Kubo can already unpin and garbage-collect old content. TGP does not create those capabilities. Its retention benefit is that it gives TruthGate a consistent boundary around which current-only, bounded-history, selected-release, or archival policies can be expressed and automated. Updating a pointer alone does not delete older CIDs or copies retained by other nodes.
See the TGP documentation for the rationale, wire specification, client resolution, publisher workflow, and gateway behavior.
TruthGate publishes static output such as HTML, CSS, JavaScript, WebAssembly, images, and other immutable assets to IPFS. It is suitable for ordinary static sites, SPAs, Blazor WebAssembly applications, and other frameworks whose production output can be served as files.
The publishing flow connects:
- a build directory or uploaded site;
- a content-addressed site CID;
- optional IPNS and TGP metadata;
- one or more mapped domains;
- automatic certificate handling and site routing.
Read the site-publishing guide.
Mapped domains are first-class configuration. TruthGate terminates TLS, obtains and renews ACME certificates, selects certificates by SNI, and routes mapped hosts to their published IPFS content.
An IP address or unmapped management host serves the authenticated TruthGate application. A mapped site host follows the site-serving path instead. This distinction allows the same appliance to provide an operator console and public websites without exposing Kubo directly.
Published domains can expose small read-only metadata endpoints that report the current site CID and IPNS/TGP state. Monitoring tools, deployment checks, and client applications can use these values without receiving private keys or administrative access.
Authenticated integrations can use API keys for supported Kubo and TruthGate operations.
The production image contains:
- the TruthGate ASP.NET application;
- the pinned Kubo version;
- the matching
ipfsCLI; - startup, migration, health, and diagnostic tooling.
The appliance is published for linux/amd64 and linux/arm64. Its root filesystem is read-only in the production Compose definition; writable application state, Kubo repository data, and Kubo blocks use persistent mounts.
A new repository is initialized as a contributing server rather than a quiet desktop node. Defaults include DHT server routing, inbound TCP/QUIC/WebTransport listeners, hole punching, relay-client support, content providing, automatic storage sizing, and repository garbage collection.
These defaults can be overridden persistently. The Kubo RPC API and HTTP gateway remain loopback-only inside the container.
TruthGate separates three persistent host paths:
data/
├── truthgate/ # application config, database, certificates, secrets, state
└── ipfs/
├── repo/ # Kubo identity, config, datastore, keystore, repo version
└── blocks/ # block files
Replacing the image does not replace those mounts. Startup checks the existing Kubo repository version and performs supported repository migration before applying managed settings.
TruthGate places request protection before expensive proxy and application work. Public endpoints, authenticated administrative paths, and gateway routes have separate policies while sharing ban, whitelist, and IPv6-prefix state.
The documentation describes the current defaults and their limits without pretending that rate limiting is a substitute for network security, monitoring, or capacity planning.
- TruthGate does not replace IPFS or Kubo.
- TruthGate is not a blockchain or a new content network.
- TruthGate does not make third-party copies of a CID disappear.
- TGP does not make old CIDs globally revocable or replace Kubo pin and garbage-collection operations.
- A mapped HTTPS domain is still an HTTP delivery path; the content remains independently addressable by CID.
- TruthGate is not intended to expose Kubo's unrestricted local RPC interface directly to anonymous internet users.
Operators, browsers, and API clients
│
▼
┌─────────────────────────────────────────────┐
│ TruthGate │
│ │
│ Accounts • Sessions • API keys • TLS │
│ Domains • Publishing • Pinning • TGP │
│ Rate protection • Metadata • Diagnostics │
└──────────────────────┬──────────────────────┘
│ loopback-only API/gateway
▼
┌─────────────────────────────────────────────┐
│ Kubo │
│ │
│ Repository • Blocks • DHT • IPNS • Bitswap │
└──────────────────────┬──────────────────────┘
│
▼
IPFS network
Read Architecture, Request routing, and Security boundaries for the detailed model.
- Docker Engine
- Docker Compose v2.24.4 or newer
- TCP ports
80,443, and4001 - UDP port
4001
Clone the repository and start the tested stable image:
git clone https://github.com/magiccodingman/TruthGate-IPFS.git
cd TruthGate-IPFS
cp .env.example .env
docker compose pull
docker compose up -dWatch the first startup:
docker compose logs -f truthgateThe log prints:
First-run administrator account: admin
First-run administrator password: <generated value>
Open https://YOUR_SERVER_IP, accept the temporary self-signed fallback certificate, sign in, and change the password.
The bootstrap password is also retained temporarily at:
data/truthgate/state/bootstrap-admin-password
It is removed after the persistent TruthGate configuration exists.
Check the container and Kubo state:
docker compose ps
docker exec truthgate truthgate-kubo-statusContinue with Docker installation and First run.
docker compose pull
docker compose up -dThe normal Compose configuration follows:
magiccodingman/truthgate-ipfs:stable
Pin TRUTHGATE_IMAGE to an exact version such as magiccodingman/truthgate-ipfs:0.1.2 when reproducibility matters more than following the moving stable channel.
Development uses the production Compose file first and the development override second:
docker compose \
-f compose.yaml \
-f compose.dev.yaml \
up --buildThe two files are merged. compose.yaml defines the real appliance contract; compose.dev.yaml changes only what development requires, including the build target, source mount, hot reload, HTTP port, writable filesystem, and NuGet caches.
New production behavior belongs in compose.yaml, not only in the development override.
See the Developer documentation, including Rider setup, Compose conventions, testing guidance, and the intentionally provisional Visual Studio page.
Start at docs/index.md.
- Installation and operations
- Developer guide
- Site publishing
- Concepts and architecture
- API documentation
- TGP protocol
- Reference
- Troubleshooting
TruthGate is active open-source infrastructure. Interfaces and behavior may continue to evolve, especially around publishing, APIs, and advanced Kubo orchestration. Exact release tags are available for deployments that should not follow moving channels.
Issues and pull requests are welcome. Documentation changes should describe current behavior, clearly label planned behavior, and avoid security or legal guarantees that the implementation cannot make.
TruthGate is maintained by MagicCodingMan. See the repository license for usage terms.