Skip to content

SPIRENS

Sovereign Portal for IPFS Resolution via Ethereum Naming Services

A modular, educational reference for self-hosting a private Web3 infrastructure stack. Clone it, add a domain as a Cloudflare zone, run the setup wizard, and bring up:

Educational reference — not production-ready

SPIRENS exists to teach the shape of a self-hosted Ethereum/IPFS/ENS stack. It is not audited, is not battle-tested, and ships no support commitment. Issues and PRs are welcome and will be looked at when time allows. If you run this on the public internet, you are the operator — own it end to end.

Endpoint What it is
https://rpc.example.com eRPC JSON-RPC — local-first, with vendor fallback & caching
https://ipfs.example.com Your branded IPFS Kubo HTTP gateway (path + *.ipfs subdomain)
https://*.ipns.example.com IPNS subdomain gateway — mutable names ({key}.ipns.example.com/…)
https://*.eth.example.com ENS → IPFS gateway via dweb-proxy
https://ens-resolver.example.com DoH endpoint Kubo uses for .eth DNSLink resolution
https://traefik.example.com Traefik dashboard (basic-auth + IP allowlist)

TLS end-to-end via Let's Encrypt (Cloudflare DNS-01). Wildcard certs included.

Who this is for

Operators who are comfortable with Docker Compose, bash, and editing YAML. You do not need to be a Kubernetes SRE or an Ethereum protocol dev. If you can run docker compose up -d, read container logs, and edit a config file, you have the prerequisites.

Three environments are first-class targets:

  • Home lab — a NAS, Mini PC, or spare desktop on your LAN.
  • Small VPS — a $5–20/month cloud VM with a public IP.
  • Dedicated server — or a bigger cloud VM if you're also hosting an Ethereum node.

Pick your deployment profile (30 seconds)

SPIRENS works in three deployment models. Decide which fits your setup before reading further — it changes which sections apply to you.

If your setup looks like… Use profile
A box on your home/office LAN, no public access needed Internal
A VPS or dedicated server with a public IP, serving the internet Public
Behind CGNAT, strict firewall, or you don't want inbound ports forwarded Tunnel

All three use the same services and configs — only the DNS and network wiring differ. See Deployment Profiles for the full breakdown and per-tool setup guides.

You'll also pick a topology (how Docker orchestrates the containers):

If you have… Use topology
One host, simpler is better single-host
Multiple hosts, want HA ingress or shared state swarm

Topology and profile are independent. A public deployment on a single VPS is public + single-host. A home lab across three Raspberry Pis is internal + swarm. Any of the six combinations works.

Quick start

Read Prerequisites first — it covers the domain, the Cloudflare token, and the hardware floor. Then:

git clone https://github.com/MysticRyuujin/spirens && cd spirens
pip install .                # install the spirens CLI
spirens setup                # interactive wizard creates .env + secrets
spirens up single            # bring the stack up (or: spirens up swarm)
spirens health               # verify all endpoints

Philosophy

SPIRENS is deliberately MVP-sized. Configs are short, readable, and single-purpose. Where the ecosystem has better documentation upstream (eRPC's caching tiers, Kubo's peering, ENS internals), we link instead of paraphrasing. The goal is to be the best on-ramp, not the endgame.

Next steps