Development Setup Guide

Обзор

Detailed guide по настройке development окружения для Saga DeFi Platform.

💻 System Requirements

Minimum Requirements

• OS: Linux (Ubuntu 20.04+), macOS 12+
• RAM: 8GB minimum, 16GB recommended
• Disk: 20GB free space
• CPU: 4 cores minimum, 8 cores recommended

Recommended Setup

• OS: Linux (Ubuntu 22.04 LTS)
• RAM: 32GB
• Disk: 50GB SSD
• CPU: 8+ cores
• Network: Stable internet connection

🛠️ Required Software

1. Go Development

# Install Go 1.21+
wget https://go.dev/dl/go1.21.0.linux-amd64.tar.gz
sudo rm -rf /usr/local/go
sudo tar -C /usr/local -xzf go1.21.0.linux-amd64.tar.gz

# Add to PATH (~/.bashrc or ~/.zshrc)
export PATH=$PATH:/usr/local/go/bin
export GOPATH=$HOME/go
export PATH=$PATH:$GOPATH/bin

# Verify installation
go version  # Should show go1.21 or higher

2. Node.js & npm

# Install Node.js 18+ (using nvm recommended)
curl -o- https://raw.githubusercontent.com/nvm-sh/nvm/v0.39.0/install.sh | bash
source ~/.bashrc  # or ~/.zshrc

nvm install 18
nvm use 18

# Verify installation
node --version  # Should show v18.x.x or higher
npm --version   # Should show 9.x.x or higher

3. Docker & Docker Compose

# Install Docker
curl -fsSL https://get.docker.com -o get-docker.sh
sudo sh get-docker.sh

# Add user to docker group (no sudo required)
sudo usermod -aG docker $USER
newgrp docker

# Verify installation
docker --version        # Should show 24.x or higher
docker compose version  # Should show 2.x or higher

4. PostgreSQL Client

# Ubuntu/Debian
sudo apt-get update
sudo apt-get install postgresql-client-15

# macOS
brew install postgresql@15

# Verify installation
psql --version  # Should show 15.x or higher

5. Foundry (Blockchain Development)

# Install Foundry
curl -L https://foundry.paradigm.xyz | bash
foundryup

# Verify installation
forge --version
anvil --version
cast --version

6. Make (Build Tool)

# Ubuntu/Debian (usually pre-installed)
sudo apt-get install build-essential

# macOS (Xcode Command Line Tools)
xcode-select --install

# Verify installation
make --version  # Should show 4.x or higher

Project Setup

1. Clone Repository

# Clone via SSH (recommended)
git clone git@github.com:aiseeq/saga.git
cd saga

# Or via HTTPS
git clone https://github.com/aiseeq/saga.git
cd saga

2. Environment Configuration

# Copy template
cp .env.example .env

# Edit .env with required values
vim .env  # or nano, code, etc.

Required environment variables:

# Database
DB_PASSWORD=aisee

# JWT Authentication
JWT_SECRET=test-jwt-secret-for-smoke-tests-minimum-32-chars-required

# HD Wallet
HD_WALLET_MASTER_ADDRESS=0xf39Fd6e51aad88F6F4ce6aB8827279cffFb92266

# Blockchain (VPS node)
BLOCKCHAIN_RPC_URL=http://188.42.218.164:8545

3. Install Dependencies

# Backend Go modules
go mod download

# Frontend Node modules
cd frontend/user-app && npm install && cd ../..
cd frontend/admin-app && npm install && cd ../..
cd frontend/e2e && npm install && cd ../..

# Blockchain Node modules
cd blockchain/local-node && npm install && cd ../..

4. Setup Git Hooks

# Install pre-commit hooks
bash scripts/setup-git-hooks.sh

# Verify hooks installed
ls -la .git/hooks/

First Run

1. Start the System

# Initial startup (builds everything)
make restart

# Verify system is running
make status

# Check logs
docker logs saga --tail=50

2. Verify Database

# Connect to database
psql -U aisee -h 127.0.0.1 -d saga

# Check tables (inside psql)
\dt

# Check sample data
SELECT * FROM users LIMIT 5;

# Exit
\q

3. Verify Blockchain

# Check VPS blockchain status
make -f makefiles/development.mk vps-status

# Should show:
# - Network ID: 1337
# - RPC URL: http://188.42.218.164:8545
# - Block Number: > 0

4. Run Tests

# Quick smoke tests (~30 seconds)
make smoke

# Unit tests (~2 minutes)
make unit

# Full test suite (~3 minutes)
make test-all

5. Access Applications

URLs:

• Admin App: http://admin.saga.local:8080/
• User App: http://app.saga.local:8080/
• API Docs: http://localhost:8080/api/docs

Configure /etc/hosts:

# Add to /etc/hosts
sudo bash -c 'echo "127.0.0.1 admin.saga.local" >> /etc/hosts'
sudo bash -c 'echo "127.0.0.1 app.saga.local" >> /etc/hosts'

IDE Configuration

VS Code

# Recommended extensions
code --install-extension golang.go
code --install-extension dbaeumer.vscode-eslint
code --install-extension esbenp.prettier-vscode
code --install-extension ms-playwright.playwright

# Settings (.vscode/settings.json)
{
  "go.useLanguageServer": true,
  "go.lintTool": "golangci-lint",
  "editor.formatOnSave": true,
  "[go]": {
    "editor.defaultFormatter": "golang.go"
  },
  "[typescript]": {
    "editor.defaultFormatter": "esbenp.prettier-vscode"
  }
}

GoLand / IntelliJ IDEA

# Enable Go modules
Settings → Go → Go Modules → Enable Go modules integration

# Configure gofmt
Settings → Tools → File Watchers → Add gofmt watcher

# Set GOROOT
Settings → Go → GOROOT → /usr/local/go

Development Tools

Useful Commands

# Development
make restart              # Restart system
make status               # Check system status
make stop                 # Stop system

# Testing
make smoke                # Quick tests
make unit                 # Unit tests
make test-all             # Full test suite
make -f makefiles/testing.mk e2e-single FILE=tests/file.spec.ts

# Code Quality
make lint                 # Run linters
make lint-fix             # Auto-fix issues

# Documentation
make analyze              # Analyze architecture
make generate-types       # Generate TypeScript types

# Versioning
make commit MESSAGE="feat: new feature"  # Commit with custom message
make commit-minor         # Minor version bump

Debugging

Backend Debugging:

# Enable debug logging
export LOG_LEVEL=debug

# Attach debugger (dlv)
dlv attach $(pgrep saga)

# View logs
docker logs saga --follow

Frontend Debugging:

# Browser DevTools
# Open http://admin.saga.local:8080
# Press F12 for DevTools

# Check Network tab for API calls
# Check Console for errors

Troubleshooting

Docker Issues

# Container won't start
docker ps -a               # Check container status
docker logs saga           # Check logs
make restart               # Force restart

# Port conflicts
lsof -i :8080              # Check what's using port
kill -9 <PID>              # Kill process

Database Issues

# Can't connect to database
pg_isready -h 127.0.0.1    # Check if PostgreSQL running

# Reset database (WARNING: destroys data)
docker exec saga /app/bin/migrate reset
docker exec saga /app/bin/migrate up

Go Module Issues

# Module cache issues
go clean -modcache
go mod download
go mod tidy

Node Module Issues

# Clear npm cache
npm cache clean --force

# Remove node_modules
rm -rf frontend/*/node_modules
rm -rf frontend/e2e/node_modules

# Reinstall
npm install

📖 Next Steps

1. ✅ Complete setup following this guide
2. ✅ Run make test-all to verify
3. ✅ Read Onboarding Guide
4. ✅ Explore Architecture Overview
5. ✅ Pick your first task

Related Documentation

• Onboarding Guide
• Testing Guide
• Deployment Guide
• Troubleshooting
• CLAUDE.md Guidelines

---

---

---

📋 Метаданные

Версия: 2.4.82

Обновлено: 2025-10-21

Статус: Published

---