4111c3acf1
- Add guides: quick-start, installation, configuration, grower, consumer, transport, vertical-farm - Add API references: REST, demand, vertical-farming - Add concepts: blockchain, seasonal-planning, carbon-footprint - Add architecture: data-flow, transport-tracking - Add vertical-farming: environmental-control, automation, integration - Add examples: seed-to-harvest, demand-driven-planting, vertical-farm-setup Completes Agent_5 documentation tasks from AGENT_REPORT.md
287 lines
4.4 KiB
Markdown
287 lines
4.4 KiB
Markdown
# 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
|