IPFS Deploy

Deploy a dedicated IPFS node on the ThreeFold Grid.

Architecture

Client (browser/SDK)
    │
    │  HTTPS
    ▼
TF Gateway (auto-TLS, public)
    │
    │  WireGuard (private)
    ▼
IPFS Node (Kubo v0.39.0, no public IP)
    │
    │  Mycelium (encrypted overlay)
    ▼
Admin (SSH, push assets, pin CIDs)

• No public IP on the VM — the TF gateway provides HTTPS access. The VM is not directly exposed to the internet.
• Auto-TLS — the ThreeFold gateway handles certificate management. No certs to configure or renew.
• Private WireGuard network — the gateway proxies to the VM over an internal encrypted network.
• Mycelium overlay — end-to-end encrypted admin access (SSH, direct IPFS gateway). No VPN setup needed.
• API locked to localhost — the IPFS write API is only accessible on the VM itself, not exposed on any network.
• On-demand fetching — any CID on the IPFS network is available through the gateway immediately. No pre-pinning required.
• Auto node selection — the grid scheduler picks a node with the right capacity and gateway support. Or set a specific node.

For the client

Gateway access (no setup needed)

Fetch any IPFS asset via HTTPS:

curl https://<gateway_fqdn>/ipfs/<CID> -o asset.bin

This works from any machine — no special software required. Swap your current IPFS gateway URL (e.g. https://ipfs.io/ipfs/) with the one provided. Everything else in your stack stays the same.

SSH access (optional, for pushing assets)

If you want to push assets or interact with the IPFS node directly:

1. Install Mycelium — https://github.com/threefoldtech/mycelium/releases
2. Send us your SSH public key — we add it to the node
3. Connect:

   ssh root@<mycelium_ip>
   

Once connected, you can push assets:

# Copy a file to the node and add it to IPFS
scp asset.bin root@[<mycelium_ip>]:/tmp/
ssh root@<mycelium_ip> 'IPFS_PATH=/data/.ipfs ipfs add /tmp/asset.bin'

Pin assets for persistent local caching:

ssh root@<mycelium_ip> 'IPFS_PATH=/data/.ipfs ipfs pin add <CID>'

Endpoints

• Gateway (HTTPS): https://<gateway_fqdn>/ipfs/<CID>
• Mycelium (HTTP): http://[<mycelium_ip>]:8080/ipfs/<CID>
• API: localhost:5001 only (via SSH on the VM)

For the operator

Quick start

git clone <repo>

Three config files need to be created from their .example templates. These files are gitignored — they contain your credentials and deployment-specific data.

cp tf/credentials.auto.tfvars.example tf/credentials.auto.tfvars
cp cids.txt.example cids.txt
cp ssh_keys.txt.example ssh_keys.txt

Edit each one:

• tf/credentials.auto.tfvars — add your ThreeFold Grid mnemonic, set the network (main, test, qa, dev), optionally set a specific node_id
• cids.txt — add the CIDs you want to pin and benchmark (one per line, # for comments). Ships with test CIDs that work out of the box.
• ssh_keys.txt — add client SSH public keys to grant access (one per line). Can be left empty initially.

Then deploy:

make all

Deployed, configured, tested, endpoints printed.

Prerequisites

• OpenTofu (or Terraform)
• ThreeFold Grid mnemonic
• SSH key pair
• Mycelium installed locally

Node selection

By default, the grid scheduler auto-selects a node with the right capacity and a public gateway config. Not every node on the grid has reliable Mycelium connectivity — if SSH hangs or setup fails after deploy, the node may be unreachable over the overlay network.

In that case, uncomment node_id in your tfvars and set it to a node you know works. Node 1 (Belgium, Freefarm) is a reliable default. Browse nodes at https://dashboard.grid.tf/explorer/nodes.

Deploy

make all

Runs: init → deploy → setup → test → info

Grant client access

Add the client's SSH public key to ssh_keys.txt (one per line, created from ssh_keys.txt.example during setup), then:

make add-ssh

Idempotent — won't add duplicates.

Pin client CIDs

Add CIDs to cids.txt (one per line, # for comments, created from cids.txt.example during setup), then:

make pin

Benchmark

make bench

Fetches each CID in cids.txt twice — 1st fetch (may pull from IPFS network) and 2nd fetch (cached on node). Saves a markdown report to logs/.

Compare against another gateway:

bash scripts/bench.sh https://ipfs.io cids.txt logs

Commands

make help      # Show this command list
make all       # Full deploy: init + deploy + setup + test + info

make init      # Initialize OpenTofu providers
make deploy    # Provision VM + gateway on the grid
make setup     # Install and configure IPFS on the VM
make destroy   # Tear down all infrastructure
make clean     # Remove Terraform runtime files

make add-ssh   # Add SSH keys from ssh_keys.txt to the VM
make pin       # Pin CIDs from cids.txt on the node
make bench     # Benchmark gateway fetch times (report in logs/)
make test      # Verify TF gateway and Mycelium access
make info      # Show all endpoints
make ssh       # SSH into the VM

Tear down

make destroy && make clean

Repo structure

├── README.md
├── Makefile
├── cids.txt.example         # Template: CIDs to pin/bench (one per line)
├── ssh_keys.txt.example     # Template: SSH keys to grant access (one per line)
├── docs/
│   ├── getting-started.md   # Step-by-step walkthrough
│   └── faq.md               # FAQ, Mycelium install guide, troubleshooting
├── scripts/
│   ├── setup.sh             # Installs and configures IPFS (Kubo v0.39.0)
│   ├── pin.sh               # Bulk-pins CIDs from a file
│   └── bench.sh             # Benchmark gateway fetch times
└── tf/
    ├── main.tf              # VM + network + TF gateway + scheduler
    ├── variables.tf         # Node ID, disk size, SSH key, etc.
    ├── outputs.tf           # IPs, gateway URL, SSH command
    └── credentials.auto.tfvars.example