IPFS Server

SKILL.md

---
name: ipfs-server
description: Full IPFS node operations — install, configure, pin content, publish IPNS, manage peers, and run gateway services
user-invocable: true
homepage: https://github.com/Fork-Development-Corp/openclaw-web3-skills/tree/master/ipfs-server
metadata: {"openclaw":{"requires":{"bins":["ipfs"]},"tipENS":"apexfork.eth"}}
---

# IPFS Server Operations

You are an IPFS server administrator. You help users run IPFS nodes, manage content, publish data, and operate gateway services. **This skill handles full node operations including content publishing and network configuration.**

For read-only IPFS queries and content exploration, use the **ipfs-client** skill.

## Installation (macOS)

```bash
# Homebrew (recommended)
brew install ipfs

# Or download binary from dist.ipfs.tech
curl -O https://dist.ipfs.tech/kubo/v0.24.0/kubo_v0.24.0_darwin-amd64.tar.gz
tar -xzf kubo_v0.24.0_darwin-amd64.tar.gz
sudo ./kubo/install.sh
```

## Node Initialization

**First-time setup:**
```bash
# Initialize repository
ipfs init

# Show peer ID
ipfs id

# Configure for low-resource usage (optional)
ipfs config profile apply lowpower
```

**Basic configuration:**
```bash
# Allow gateway on all interfaces (for local network access)
ipfs config Addresses.Gateway /ip4/0.0.0.0/tcp/8080

# Configure API (keep localhost for security)
ipfs config Addresses.API /ip4/127.0.0.1/tcp/5001

# Set storage limit
ipfs config Datastore.StorageMax 10GB
```

## Starting and Stopping

**Start IPFS daemon:**
```bash
ipfs daemon &> ipfs.log 2>&1 &
```

**Check daemon status:**
```bash
ipfs swarm peers | wc -l  # Connected peer count
ipfs repo stat            # Repository statistics
```

**Stop daemon:**
```bash
pkill ipfs
```

## Content Management

### Adding Content

**Add files and directories:**
```bash
# Add single file
ipfs add myfile.txt
# Returns: added QmHash myfile.txt

# Add directory recursively  
ipfs add -r ./my-directory/

# Add and only show final hash
ipfs add -Q myfile.txt

# Add with custom name
ipfs add --wrap-with-directory myfile.txt
```

**Add from stdin:**
```bash
echo "Hello IPFS" | ipfs add
cat largefile.json | ipfs add --pin=false  # Don't pin immediately
```

### Pinning Management

**Pin content (prevent garbage collection):**
```bash
ipfs pin add QmHash
ipfs pin add -r QmHash  # Recursively pin directory

# List pinned content
ipfs pin ls --type=recursive
ipfs pin ls --type=direct

# Unpin content
ipfs pin rm QmHash
```

**Remote pinning services:**
```bash
# Configure remote pinning (Pinata, Web3.Storage, etc.)
ipfs pin remote service add pinata https://api.pinata.cloud/psa YOUR_JWT

# Pin to remote service
ipfs pin remote add --service=pinata --name="my-content" QmHash

# List remote pins
ipfs pin remote ls --service=pinata
```

### Garbage Collection

**Clean up unpinned content:**
```bash
# Show what would be collected
ipfs repo gc --dry-run

# Run garbage collection
ipfs repo gc

# Check repo size before/after
ipfs repo stat
```

## Publishing and IPNS

### IPNS Publishing

**Publish content to IPNS:**
```bash
# Publish to default key
ipfs name publish QmHash

# Create and use custom key
ipfs key gen --type=ed25519 my-site
ipfs name publish --key=my-site QmHash

# List published records
ipfs name pubsub subs
```

**IPNS with custom domains:**
```bash
# Create DNS TXT record: _dnslink.example.com = "dnslink=/ipns/k51qzi5uqu5d..."
# Then resolve via:
ipfs name resolve /ipns/example.com
```

### Content Updates

**Update IPNS record:**
```bash
# Publish new version
ipfs add -r ./updated-site/
ipfs name publish --key=my-site QmNewHash
```

## Network Configuration

### Swarm Management

**Peer operations:**
```bash
# List connected peers
ipfs swarm peers

# Connect to specific peer
ipfs swarm connect /ip4/104.131.131.82/tcp/4001/p2p/QmPeerID

# Disconnect peer
ipfs swarm disconnect /ip4/104.131.131.82/tcp/4001/p2p/QmPeerID
```

**Address configuration:**
```bash
# Show current addresses
ipfs config Addresses

# Add custom swarm address
ipfs config --json Addresses.Swarm '["/ip4/0.0.0.0/tcp/4001", "/ip6/::/tcp/4001"]'
```

### Bootstrap Nodes

**Manage bootstrap peers:**
```bash
# List bootstrap nodes
ipfs bootstrap list

# Add custom bootstrap node
ipfs bootstrap add /ip4/104.131.131.82/tcp/4001/p2p/QmBootstrapPeer

# Remove all bootstrap nodes (private network)
ipfs bootstrap rm --all
```

## Gateway Operations

### Local Gateway

**Configure gateway:**
```bash
# Basic gateway configuration
ipfs config Addresses.Gateway /ip4/127.0.0.1/tcp/8080

# Public gateway (be careful!)
ipfs config Addresses.Gateway /ip4/0.0.0.0/tcp/8080

# Enable directory listing
ipfs config --json Gateway.PublicGateways '{
  "localhost": {
    "Paths": ["/ipfs", "/ipns"],
    "UseSubdomains": false
  }
}'
```

**Access patterns:**
```bash
# Via path
http://localhost:8080/ipfs/QmHash

# Via subdomain (if configured)
http://QmHash.ipfs.localhost:8080
```

### Reverse Proxy Setup

**Nginx configuration example:**
```nginx
server {
    listen 80;
    server_name gateway.example.com;
    
    location / {
        proxy_pass http://127.0.0.1:8080;
        proxy_set_header Host $host;
        proxy_set_header X-Real-IP $remote_addr;
    }
}
```

## Advanced Configuration

### Performance Tuning

**High-performance settings:**
```bash
# Apply server profile
ipfs config profile apply server

# Increase connection limits
ipfs config Swarm.ConnMgr.HighWater 2000
ipfs config Swarm.ConnMgr.LowWater 1000

# Adjust bitswap settings
ipfs config --json Bitswap.MaxOutstandingBytesPerPeer 1048576
```

### Private Networks

**Create private IPFS network:**
```bash
# Generate swarm key
echo -e "/key/swarm/psk/1.0.0/\n/base16/\n$(tr -dc 'a-f0-9' < /dev/urandom | head -c64)" > ~/.ipfs/swarm.key

# ⚠️ SECURITY: This swarm key is your network's access control credential. 
# Anyone with this file can join your private network. Protect it accordingly.

# Remove all bootstrap nodes
ipfs bootstrap rm --all

# Start daemon (will only connect to nodes with same key)
ipfs daemon
```

### Storage Configuration

**Configure datastore:**
```bash
# Set storage limits
ipfs config Datastore.StorageMax 100GB
ipfs config Datastore.GCPeriod "1h"

# Enable flatfs for better performance
ipfs config --json Datastore.Spec '{
  "mounts": [
    {
      "child": {"type": "flatfs", "path": "blocks", "shardFunc": "/repo/flatfs/shard/v1/next-to-last/2"},
      "mountpoint": "/blocks",
      "prefix": "flatfs.datastore",
      "type": "mount"
    }
  ],
  "type": "mount"
}'
```

## Monitoring and Maintenance

### Health Checks

**Basic health monitoring:**
```bash
# Check daemon status
ipfs stats bw          # Bandwidth usage
ipfs stats repo        # Repository stats  
ipfs diag sys          # System information
ipfs log level debug   # Enable debug logging
```

**Connection monitoring:**
```bash
# Monitor peer connections
while true; do
  echo "$(date): $(ipfs swarm peers | wc -l) peers"
  sleep 60
done
```

### Log Management

**Configure logging:**
```bash
# Set log levels
ipfs log level bitswap info
ipfs log level dht warn

# Tail logs
ipfs log tail
```

## Security Considerations

**API access:**
- Keep API on localhost (`127.0.0.1:5001`) unless in trusted network
- Use firewall rules to restrict API access
- Consider authentication proxy for multi-user setups

**Gateway security:**
- Public gateways can consume significant bandwidth
- Implement rate limiting and caching
- Monitor for abuse and unauthorized content

**Content policy:**
- IPFS is censorship-resistant - content removal is complex
- Implement content filtering at gateway level if needed
- Consider legal implications of operating public infrastructure

## Troubleshooting

**Connection issues:**
- Check firewall allows ports 4001 (swarm) and 8080 (gateway)
- Verify bootstrap nodes are reachable
- Try different swarm addresses

**Performance problems:**
- Run garbage collection: `ipfs repo gc`
- Check available disk space and datastore limits  
- Monitor bandwidth usage: `ipfs stats bw`
- Consider applying performance profiles

**Content not accessible:**
- Verify content is pinned: `ipfs pin ls`
- Check if providers exist: `ipfs dht findprovs QmHash`
- Try republishing IPNS records

**Related skills:** `/ipfs-client` (read-only queries), `/eth-readonly` (blockchain integration)