localgreenchain/docs/guides/installation.md

Installation Guide

Complete installation instructions for LocalGreenChain.

System Requirements

Minimum Requirements

Component	Requirement
OS	macOS, Linux, Windows (WSL2)
Runtime	Bun 1.0+
Memory	2GB RAM
Storage	500MB free space
Node.js	18+ (optional, Bun preferred)

Recommended

Component	Recommendation
Memory	4GB+ RAM
Storage	2GB+ free space
CPU	Multi-core processor

Installation Methods

Method 1: Bun (Recommended)

Bun provides the fastest installation and runtime performance.

Install Bun

# macOS/Linux/WSL
curl -fsSL https://bun.sh/install | bash

# Verify installation
bun --version

Clone and Install

git clone https://github.com/yourusername/localgreenchain.git
cd localgreenchain
bun install

Start Development Server

bun run dev

Method 2: npm/Node.js

If you prefer npm:

git clone https://github.com/yourusername/localgreenchain.git
cd localgreenchain
npm install
npm run dev

Method 3: Docker

For containerized deployment:

# Clone repository
git clone https://github.com/yourusername/localgreenchain.git
cd localgreenchain

# Build and run
docker build -t localgreenchain .
docker run -p 3001:3001 localgreenchain

Method 4: Docker Compose

For full stack with optional services:

# Standard deployment
docker-compose up -d

# With Tor support
docker-compose -f docker-compose.tor.yml up -d

Environment Setup

Create Environment File

cp .env.example .env

Essential Variables

# Server Configuration
PORT=3001
NODE_ENV=development

# API Keys (optional)
PLANTS_NET_API_KEY=your_api_key_here

# Privacy Options
TOR_ENABLED=false
LOCATION_PRIVACY=city  # exact, fuzzy, city, country, hidden

Full Configuration

See Configuration Guide for all available options.

Database Setup

Default: JSON File Storage

LocalGreenChain uses JSON file storage by default:

data/
├── plantchain.json      # Main blockchain
├── transport.json       # Transport events
└── users.json           # User data

No additional setup required - files are created automatically.

Optional: PostgreSQL

For production deployments with high volume:

# Install PostgreSQL
sudo apt install postgresql

# Create database
createdb localgreenchain

# Configure in .env
DATABASE_URL=postgresql://user:pass@localhost:5432/localgreenchain

Verification

Check Installation

# Run tests
bun test

# Check build
bun run build

# Verify API
curl http://localhost:3001/api/plants/network

Expected Output

{
  "success": true,
  "data": {
    "totalPlants": 0,
    "chainLength": 1,
    "difficulty": 3
  }
}

Platform-Specific Notes

macOS

# Install Xcode Command Line Tools if needed
xcode-select --install

Linux (Ubuntu/Debian)

# Install build essentials
sudo apt update
sudo apt install build-essential

Windows (WSL2)

# Enable WSL2 first
wsl --install

# Then follow Linux instructions inside WSL

Updating

Update to Latest Version

git pull origin main
bun install
bun run build

Migrate Data

Data migrations are automatic. Backup before updating:

cp -r data/ data-backup/

Uninstallation

Remove LocalGreenChain

# Stop server
# Remove directory
rm -rf localgreenchain/

# Remove global Bun packages (if installed globally)
bun remove -g localgreenchain

Keep Data

To preserve your blockchain data:

cp -r data/ ~/localgreenchain-backup/

Troubleshooting

Common Issues

Bun Installation Fails

# Try alternative installation
npm install -g bun

# Or download binary directly
curl -fsSL https://bun.sh/install | bash -s "bun-v1.0.0"

Port Conflict

# Find process using port
lsof -i :3001

# Kill process
kill -9 <PID>

# Or use different port
PORT=3002 bun run dev

Permission Denied

# Fix permissions
chmod +x node_modules/.bin/*

Out of Memory

# Increase Node.js memory limit
export NODE_OPTIONS="--max-old-space-size=4096"

Next Steps

• Configuration Guide - Customize your setup
• Quick Start - Register your first plant
• Grower Guide - Full grower workflow