ipfs-bootstrap

Bootstrap, operate, and monitor a production-friendly IPFS/Kubo node from one CLI.

Why this exists

Standing up IPFS in production is usually a patchwork of install docs, daemon config, service wiring, and provider-specific pin flows. ipfs-bootstrap gives teams one predictable CLI that handles setup and daily operations with sane defaults.

Product focus

ipfs-bootstrap is strongest when you use it as an operator CLI for Kubo nodes:

• install or locate Kubo
• initialize a repo safely
• apply sane dev/prod config
• run health checks and lifecycle commands
• wire the node into a service manager
• handle backup, restore, GC, usage, and gateway checks

The Web3/NFT, cluster, and proxy helpers are included, but the core product is reliable node bootstrap + operations.

What is stable today

• Local node bootstrap and lifecycle flows
• Repo health, usage, gateway, backup, and restore commands
• CID, URI, IPNS, CAR, and pinning helpers

What to validate before production rollout

• Your preferred service manager path (systemd, launchd, windows-service, or pm2)
• Remote pin provider credentials and quotas
• Cluster topology and replication behavior in your own environment
• Firewall / reverse proxy rules around gateway exposure

Quickstart

npm i -g ipfs-bootstrap

ipfs-bootstrap init
ipfs-bootstrap configure --profile dev --cors "*"
ipfs-bootstrap up
ipfs-bootstrap add ./asset.png
ipfs-bootstrap nft:upload ./art.png --name "My NFT" --description "First mint"

Start here in 60 seconds

ipfs-bootstrap init
ipfs-bootstrap configure --profile dev --cors "*"
ipfs-bootstrap up
ipfs-bootstrap status
ipfs-bootstrap doctor

If that works, you have a usable local node. From there you can add content, pin remotely, wire a service manager, or generate proxy config.

Core operator workflows

1) Bring up a node

ipfs-bootstrap init
ipfs-bootstrap configure --profile prod --cors "https://app.example.com"
ipfs-bootstrap up

2) Check health and usage

ipfs-bootstrap status
ipfs-bootstrap doctor
ipfs-bootstrap usage --json

3) Publish and pin content

ipfs-bootstrap add ./asset.png
ipfs-bootstrap pin <cid> --provider pinata --token "$PINATA_JWT"

4) Make it production-facing

ipfs-bootstrap service install --manager systemd
ipfs-bootstrap gateway check
ipfs-bootstrap proxy --format nginx --domain ipfs.example.com --output ipfs.conf

Commands

Setup

ipfs-bootstrap init [--mode auto|privileged|user] [--install-dir <path>] [--data-dir <path>] [--version <kubo-version>]
ipfs-bootstrap configure [--profile dev|prod] [--api-port <n>] [--gateway-port <n>] [--cors <csv>]
ipfs-bootstrap up
ipfs-bootstrap down
ipfs-bootstrap service <install|status> [--manager systemd|launchd|windows-service|pm2]

Node Ops

ipfs-bootstrap status [--json]
ipfs-bootstrap doctor [--json]
ipfs-bootstrap gc [--json]
ipfs-bootstrap gc:schedule <enable|disable|status> [--interval hourly|daily|weekly|monthly]
ipfs-bootstrap stats [--json]
ipfs-bootstrap usage [--json]
ipfs-bootstrap backup [--output <file>]
ipfs-bootstrap restore <backup-file>

Content

ipfs-bootstrap add <path> [--json]
ipfs-bootstrap pin <cid> [--provider local|pinata|web3storage|infura] [--token <token>] [--name <name>]
ipfs-bootstrap uri <cid> [--scheme ipfs|https] [--gateway <url>] [--token-id <id>]
ipfs-bootstrap cid inspect <cid> [--json]
ipfs-bootstrap cid convert <cid> [--to v0|v1] [--json]

IPNS

ipfs-bootstrap ipns publish <cid> [--key <name>] [--lifetime <duration>]
ipfs-bootstrap ipns resolve <name>
ipfs-bootstrap ipns keys

CAR Files

ipfs-bootstrap car export <cid> [--output <file>]
ipfs-bootstrap car import <file.car>

NFT / Web3

ipfs-bootstrap nft:metadata --name <name> [--description <text>] [--image-cid <cid>] [--attributes '<json>']
ipfs-bootstrap nft:collection <assets-dir> --name <name> [--description <text>] [--output-dir <dir>] [--json]
ipfs-bootstrap nft:upload <image> --name <name> [--description <text>] [--attributes '<json>'] [--json]

Cluster

ipfs-bootstrap cluster init [--secret <hex>]
ipfs-bootstrap cluster start
ipfs-bootstrap cluster stop
ipfs-bootstrap cluster status [--json]
ipfs-bootstrap cluster peers [--json]
ipfs-bootstrap cluster pin <cid> [--name <n>] [--replication-min <n>] [--replication-max <n>] [--json]
ipfs-bootstrap cluster unpin <cid>

Monitoring

ipfs-bootstrap gateway check [--gateways <csv>] [--timeout <ms>] [--json]

Infrastructure

ipfs-bootstrap proxy [--format nginx|caddy] [--domain <domain>] [--output <file>]

Real Examples

# Init in user mode (no sudo)
ipfs-bootstrap init --mode user

# Production config
ipfs-bootstrap configure --profile prod --cors "https://app.example.com"

# Service + health
ipfs-bootstrap service install --manager systemd
ipfs-bootstrap doctor --json

# Pin to Pinata
ipfs-bootstrap pin <cid> --provider pinata --token "$PINATA_JWT"

# Pin to Infura
ipfs-bootstrap pin <cid> --provider infura --token "$INFURA_PROJECT_ID" --secret "$INFURA_SECRET"

# Upload image + metadata in one step
ipfs-bootstrap nft:upload ./art.png --name "Sword #1" --attributes '[{"trait_type":"Rarity","value":"Legendary"}]'

# Full NFT collection workflow
ipfs-bootstrap nft:collection ./art --name "Genesis Collection" --description "First drop"
# -> uploads all assets, generates per-token metadata, returns base URI

# Inspect and convert CIDs
ipfs-bootstrap cid inspect QmYwAPJzv5CZsnN625s3Xf2nemtYgPpHdWEz79ojWnPbdG
ipfs-bootstrap cid convert QmYwAPJzv5CZsnN625s3Xf2nemtYgPpHdWEz79ojWnPbdG --to v1

# Gateway health check
ipfs-bootstrap gateway check
ipfs-bootstrap gateway check --gateways "https://ipfs.io,https://dweb.link" --json

# Schedule automatic garbage collection
ipfs-bootstrap gc:schedule enable --interval daily
ipfs-bootstrap gc:schedule status

# Bandwidth and storage report
ipfs-bootstrap usage --json

# IPFS Cluster replication
ipfs-bootstrap cluster init
ipfs-bootstrap cluster start
ipfs-bootstrap cluster pin <cid> --replication-min 2 --replication-max 3

# Publish to IPNS for mutable pointer
ipfs-bootstrap ipns publish <baseCID> --lifetime 48h

# Export for offline/archive
ipfs-bootstrap car export <cid> --output archive.car

# Generate reverse proxy config
ipfs-bootstrap proxy --format nginx --domain ipfs.mysite.com --output /etc/nginx/conf.d/ipfs.conf

Remote Pin Providers

• --provider local (default)
• --provider pinata --token <JWT>
• --provider web3storage --token <token>
• --provider infura --token <projectId> --secret <projectSecret>

Or set env vars:

export IPFS_BOOTSTRAP_PIN_TOKEN=...
export IPFS_BOOTSTRAP_PIN_SECRET=...   # required for Infura

Architecture

1. init -> detect OS, install/locate Kubo, initialize repo
2. configure -> apply API/gateway ports, CORS, profile presets
3. up/down -> daemon lifecycle
4. service install -> systemd / launchd / NSSM / PM2
5. add/pin -> content to local node + optional remote provider (Pinata, web3.storage, Infura)
6. cid -> CID validation, inspection, and v0/v1 conversion
7. ipns -> mutable name publishing/resolution
8. car -> DAG import/export for archival
9. nft:metadata/collection/upload -> chain-ready metadata generation + one-step upload
10. cluster -> IPFS Cluster setup, peer management, replicated pinning
11. gateway -> health monitoring for local and public gateways
12. gc:schedule -> automated garbage collection scheduling (cron/launchd/Task Scheduler)
13. usage -> bandwidth and storage usage reporting
14. proxy -> reverse proxy config generation
15. gc/stats/backup/restore -> node maintenance

License + Links

• License: MIT
• Changelog: CHANGELOG.md
• npm: https://www.npmjs.com/package/ipfs-bootstrap
• GitLab: https://gitlab.com/darks0l/ipfs-bootstrap

Built with teeth. 🌑