# 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

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

# Verify installation
bun --version
```

#### Clone and Install

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

#### Start Development Server

```bash
bun run dev
```

### Method 2: npm/Node.js

If you prefer npm:

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

### Method 3: Docker

For containerized deployment:

```bash
# 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:

```bash
# Standard deployment
docker-compose up -d

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

## Environment Setup

### Create Environment File

```bash
cp .env.example .env
```

### Essential Variables

```bash
# 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](./configuration.md) 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:

```bash
# Install PostgreSQL
sudo apt install postgresql

# Create database
createdb localgreenchain

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

## Verification

### Check Installation

```bash
# Run tests
bun test

# Check build
bun run build

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

### Expected Output

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

## Platform-Specific Notes

### macOS

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

### Linux (Ubuntu/Debian)

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

### Windows (WSL2)

```bash
# Enable WSL2 first
wsl --install

# Then follow Linux instructions inside WSL
```

## Updating

### Update to Latest Version

```bash
git pull origin main
bun install
bun run build
```

### Migrate Data

Data migrations are automatic. Backup before updating:

```bash
cp -r data/ data-backup/
```

## Uninstallation

### Remove LocalGreenChain

```bash
# 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:

```bash
cp -r data/ ~/localgreenchain-backup/
```

## Troubleshooting

### Common Issues

#### Bun Installation Fails

```bash
# 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

```bash
# Find process using port
lsof -i :3001

# Kill process
kill -9 <PID>

# Or use different port
PORT=3002 bun run dev
```

#### Permission Denied

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

#### Out of Memory

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

## Next Steps

- [Configuration Guide](./configuration.md) - Customize your setup
- [Quick Start](./quick-start.md) - Register your first plant
- [Grower Guide](./grower-guide.md) - Full grower workflow