Nostr IPFS File Store

An open-source, decentralized profile storage solution that integrates IPFS with Nostr for secure, permanent storage of profile data and images. Built by the community, for the community.

Prerequisites

• Node.js v16 or higher
• IPFS daemon (optional, will run embedded node)
• Redis server (required for caching and session management)
• Nostr key pair (required)
  • npub (public key) for authentication
  • nsec (private key) for signing updates
  • Or hex format keys from a Nostr client/extension

Features

• 🖼️ Profile image storage on IPFS
• 🔐 Nostr authentication and signing
• 🌐 Standard IPFS ports and gateway
• 📝 Profile metadata management
• 🔄 Automatic pinning of uploaded content
• 💾 Persistent IPFS storage across restarts
• 🔍 Enhanced health monitoring and diagnostics
• ⚡ Improved file upload performance
• 🧹 Automatic file expiration management
• 📊 IPFS node statistics and peer tracking
• 📈 Storage quota management
• 🔒 Trusted npubs middleware
• 🚦 Advanced error handling
• 📋 File upload validation
• 🏥 Health check system

🌟 Why Open Source?

We believe in the power of open collaboration and transparency. This project aims to:

• Foster innovation in the Nostr ecosystem
• Provide a reference implementation for IPFS+Nostr integration
• Enable community-driven improvements
• Build trust through code transparency
• Support decentralization principles

🚀 Quick Start

# Clone the repository
git clone https://github.com/HumanjavaEnterprises/nostr-ipfs-file-store.git
cd nostr-ipfs-file-store

# Install Redis (if not already installed)
# On macOS:
brew install redis
brew services start redis
# On Linux:
sudo apt-get update
sudo apt-get install redis-server
sudo systemctl start redis-server

# Install dependencies
npm install

# Configure environment
cp .env.example .env
# Edit .env with your settings

# Start the service
npm start

🔧 Development vs Production

Local Development

For local development, run the service directly from your workspace:

# Start in development mode
npm run dev

# Or use PM2 for development
pm2 start ecosystem.config.cjs

Production Deployment

For production, follow the standardized deployment process:

# On production server
git clone https://github.com/HumanjavaEnterprises/nostr-ipfs-file-store.git
cp nostr-ipfs-file-store/deploy.sh ~/deploy-ipfs.sh
chmod +x ~/deploy-ipfs.sh
./deploy-ipfs.sh

See Deployment Guide for detailed instructions.

Project Structure

.
├── deploy/                 # Deployment configurations
│   ├── nginx/             # Nginx configuration files
│   └── scripts/           # Deployment scripts
├── scripts/               # Utility scripts
│   ├── check-ipfs.js      # IPFS connection checker
│   ├── dev-startup.sh     # Development startup script
│   ├── generate-keys.sh   # Key generation script
│   ├── setup-profile.js   # Profile setup utility
│   ├── shutdown.sh        # Shutdown script
│   └── startup.sh         # Production startup script
├── src/                   # Source code
├── dist/                  # Compiled code
├── docs/                  # Documentation
└── test/                  # Test files

Configuration

Environment Variables

Key environment variables for configuration:

# IPFS Configuration
IPFS_HOST=localhost
IPFS_PORT=5001
IPFS_PROTOCOL=http
IPFS_API=http://localhost:5001
IPFS_PUBLIC_GATEWAY=https://ipfs.io
IPFS_MAX_FILE_SIZE=5242880  # 5MB

# File Expiration Configuration
ENABLE_FILE_EXPIRATION=true
FILE_EXPIRATION_DAYS=90
CLEANUP_INTERVAL_HOURS=24
KEEP_PINNED_FILES=true

# See .env.example for complete list

Health Monitoring

The service now includes enhanced health monitoring endpoints:

• /health/ipfs - IPFS node status and statistics
• /health/peers - Connected peer count and status
• /health/repo - Repository statistics and disk usage

File Management

New file management features:

• Automatic file expiration after configurable period
• Configurable cleanup intervals
• Option to preserve pinned files
• Enhanced upload performance with streaming
• Improved error handling and logging

Recent Updates

IPFS Service Enhancements

• Added comprehensive health check endpoints
• Implemented file expiration management
• Improved file upload performance
• Added public gateway URL configuration
• Enhanced error handling and logging

TypeScript Improvements

• Fixed type definitions in IPFS service
• Added proper typing for CID handling
• Improved code organization and modularity
• Enhanced type safety across services

Documentation

• Updated deployment guide with new configuration options
• Added health monitoring documentation
• Improved maintenance guide with new features
• Updated architecture documentation

Installation

# Clone the repository
git clone https://github.com/HumanjavaEnterprises/nostr-ipfs-file-store.git
cd nostr-ipfs-file-store

# Install Redis (if not already installed)
# On macOS:
brew install redis
brew services start redis
# On Linux:
sudo apt-get update
sudo apt-get install redis-server
sudo systemctl start redis-server

# Install dependencies
npm install

# Configure environment
cp .env.example .env
# Edit .env with your settings

Running with PM2

# Start the service
npm run pm2:start

# View logs
npm run pm2:logs

# Stop the service
npm run pm2:stop

API Endpoints

Profile Management

• POST /api/profile/image

  • Upload profile image
  • Requires Nostr pubkey in header: x-nostr-pubkey
  • Returns IPFS CID and Nostr event

• GET /api/profile/image/:cid

  • Retrieve profile image by CID

• POST /api/profile/metadata

  • Update profile metadata
  • Requires Nostr signed event

IPFS Gateway

• GET /ipfs/:cid
  • Direct access to IPFS content

Nostr Integration

This service requires Nostr for authentication and profile management. Users must have:

1. A Nostr public key (npub) for:

   • Authentication
   • Profile ownership verification
   • Content association

2. A Nostr private key (nsec) for:

   • Signing profile updates
   • Authorizing changes
   • Creating valid Nostr events

Keys can be:

• Generated using Nostr clients
• Managed via browser extensions (e.g., Alby, nos2x)
• Provided in hex format for programmatic use

Event Types

• Kind 0: Profile metadata
• Kind 1: Profile updates
• Custom kinds: Extended profile data

Security Considerations

• Never share your nsec (private key)
• Always sign events client-side
• Verify signatures server-side
• Use secure relays for Nostr communication

Deployment

Important Safety Note ⚠️

The deployment script must be run from outside the project directory to ensure a safe and reliable deployment process. This prevents any potential issues with the script trying to modify itself during deployment.

Deployment Steps

1. Copy the deploy script to the parent directory:

   cp deploy.sh ../deploy-ipfs-noster.sh

2. Change to the parent directory:

   cd ..

3. Make the script executable:

   chmod +x deploy-ipfs-noster.sh

4. Run the deployment:

   ./deploy-ipfs-noster.sh

What the Deploy Script Does

The deployment script performs the following tasks:

• Creates necessary directories if they don't exist
• Copies the project files to the deployment location
• Sets up environment variables and configurations
• Installs dependencies
• Starts/restarts the service using PM2

Post-Deployment

After deployment, verify that:

1. The service is running (pm2 status)
2. The logs show no errors (pm2 logs ipfs.noster)
3. The API endpoints are accessible

🤝 Contributing

We welcome contributions from the community! See our Contributing Guidelines for details on how to:

• Submit bug reports
• Propose new features
• Create pull requests
• Join the discussion

📖 Documentation

Core Documentation

• Optimization Guide - Detailed guide for optimizing IPFS node performance
  • Pinning strategies
  • Gateway configuration
  • Resource management
  • Performance tuning
  • Caching implementation
  • Content preprocessing
  • Monitoring setup
  • Backup strategies
• IPFS Data Persistence - Details about IPFS data storage and server restart handling

Performance Optimization

The IPFS Profile Store is optimized for handling profile images and user content. Key optimizations include:

• Smart Pinning: Automatically manages content based on user activity
• Caching: Two-tier caching system for hot and warm content
• Image Processing: Automatic optimization of uploaded images
• Resource Management: Configurable storage limits and garbage collection
• Monitoring: Comprehensive metrics collection and alerting

For detailed optimization settings and strategies, see our Optimization Guide.

🔐 Security

Security is a top priority. We follow these principles:

• Regular security audits
• Community security reviews
• Responsible disclosure policy
• No private key handling server-side

🌐 Community

• Join our Discord
• Follow us on Twitter
• Star us on GitHub

📜 License

MIT License - see LICENSE file for details

🙏 Acknowledgments

Built with love by the Nostr community. Special thanks to:

• Nostr Protocol
• IPFS
• Helia
• All our contributors