ipfs-overlay

Purpose

Deploy IPFS nodes inside Kubernetes and bind them to the ZeroTier overlay network for secure, decentralized storage.

Part of the FlatRacoon Network Stack.

Architecture

 ┌─────────────────────┐
│ Public IPFS │
│ (optional gate) │
└──────────┬──────────┘
│ (if enabled)
┌──────────▼──────────┐
│ Gateway Node │
│ (public bridge) │
└──────────┬──────────┘
│
┌───────────────────────┼───────────────────────┐
│ ZeroTier Overlay (encrypted mesh) │
└───────────────────────┼───────────────────────┘
│
┌───────────────────────┼───────────────────────┐
│ │ │
┌──────▼──────┐ ┌──────▼──────┐ ┌──────▼──────┐
│ IPFS Node │◄───────►│ IPFS Node │◄───────►│ IPFS Node │
│ (private) │ swarm │ (private) │ swarm │ (private) │
└─────────────┘ └─────────────┘ └─────────────┘

Components

• IPFS daemon configuration - Kubo node settings for private operation

• Kubernetes manifests - StatefulSet, PVC, Services

• Bootstrap and peer discovery - Private swarm key, bootstrap list

• Private routing - ZeroTier-only binding, no public DHT

Directory Structure

ipfs-overlay/
├── manifests/
│ ├── statefulset.yaml # IPFS nodes with persistent storage
│ ├── service.yaml # Internal cluster service
│ ├── pvc.yaml # Persistent volume claims
│ ├── configmap.yaml # IPFS configuration
│ └── secret.yaml # Swarm key
├── configs/
│ ├── ipfs-config.ncl # Nickel IPFS configuration
│ ├── swarm.ncl # Swarm key generation
│ └── bootstrap.ncl # Bootstrap peer list
├── scripts/
│ ├── init-node.sh # Node initialization
│ ├── generate-swarm-key.sh
│ └── health-check.sh
├── Justfile
├── README.adoc
├── .machine_readable/6a2/STATE.a2ml
├── .machine_readable/6a2/META.a2ml
└── .machine_readable/6a2/ECOSYSTEM.a2ml

Inputs

Input	Description	Source
IPFS_SWARM_KEY	Private swarm encryption key	Generated or poly-secret-mcp
Bootstrap nodes	Initial peer addresses	configs/bootstrap.ncl
ZeroTier interface	Network interface for binding	zerotier-k8s-link
Storage class	Kubernetes storage provisioner	Cluster configuration

Outputs

Output	Description
Private IPFS cluster	Encrypted, ZeroTier-bound IPFS swarm
Distributed storage layer	Content-addressed storage for stack
Gateway (optional)	HTTP gateway for content retrieval
Pinning service	Persistent content pinning

Integration Points

With FlatRacoon Stack

• zerotier-k8s-link - IPFS binds exclusively to ZT interface

• twingate-helm-deploy - External access via Twingate gateway

• poly-observability-mcp - Storage metrics and health

Machine-Readable Manifest

{
"module": "ipfs-overlay",
"version": "0.1.0",
"layer": "storage",
"requires": ["kubernetes", "zerotier-k8s-link"],
"provides": ["distributed-storage", "content-addressing", "pinning"],
"config_schema": "configs/schema.ncl",
"health_endpoint": "/ipfs/health",
"metrics_endpoint": "/ipfs/metrics",
"api_endpoint": "/api/v0"
}

Quick Start

# 1. Ensure ZeroTier overlay is running
just -f ../zerotier-k8s-link/Justfile status
# 2. Generate or retrieve swarm key
just generate-swarm-key
# Or: just fetch-swarm-key # from Vault# 3. Deploy IPFS nodes
just deploy
# 4. Verify cluster formation
just cluster-status
# 5. Test content pinningecho"Hello FlatRacoon"| just pin-content

Private Swarm Configuration

Swarm Key Generation

# Generate new swarm keyecho -e "/key/swarm/psk/1.0.0/\n/base16/\n$(tr -dc 'a-f0-9'< /dev/urandom | head -c 64)"> swarm.key

IPFS Config for Private Operation

{
"Bootstrap": [],
"Addresses": {
"Swarm": [
"/ip4/0.0.0.0/tcp/4001",
"/ip6/::/tcp/4001"
],
"API": "/ip4/127.0.0.1/tcp/5001",
"Gateway": "/ip4/127.0.0.1/tcp/8080"
},
"Swarm": {
"AddrFilters": null,
"DisableBandwidthMetrics": false,
"DisableNatPortMap": true
},
"Discovery": {
"MDNS": {
"Enabled": false
}
},
"Routing": {
"Type": "none"
}
}

Status

Phase	Production-ready
Completion	100%
Next	Helm chart alternative, automated cluster scaling

License

MPL-2.0

Architecture

See TOPOLOGY.md for a visual architecture map and completion dashboard.