Environment Setup Guide¶

🖥️ System Requirements¶

Минимальные требования:¶

OS: Linux (Ubuntu 20.04+), macOS 11+, или Windows WSL2
RAM: 8GB minimum (16GB recommended)
Disk: 20GB free space
CPU: 4 cores minimum

Required Software:¶

Go: 1.21+ (installation)
Node.js: 20.x LTS (nvm recommended)
PostgreSQL: 15+ (download)
Docker: 24+ (installation)
Git: 2.x+

Initial Setup¶

1. Clone Repository¶

# Clone Saga repository
git clone https://github.com/your-org/saga.git
cd saga

# Verify structure
ls -la
# Should see: backend/, frontend/, blockchain/, config/, docs/, tools/

2. Install Go Dependencies¶

# Navigate to backend
cd backend

# Install dependencies
go mod download

# Verify installation
go version
go mod verify

3. Install Node.js Dependencies¶

# Install for user-app
cd frontend/user-app
npm install

# Install for admin-app
cd ../admin-app
npm install

# Install for E2E tests
cd ../e2e
npm install

4. Setup PostgreSQL Database¶

Create Database:

# Connect to PostgreSQL
psql -U postgres

# Create user
CREATE USER aisee WITH PASSWORD 'aisee';

# Create database
CREATE DATABASE saga OWNER aisee;

# Grant privileges
GRANT ALL PRIVILEGES ON DATABASE saga TO aisee;

# Exit
\q

Verify Connection:

PGPASSWORD=aisee psql -U aisee -h 127.0.0.1 -d saga -c "SELECT version()"

5. Configure Environment Variables¶

Create .env file:

# In project root
cat > .env << 'EOF'
# Database
DB_HOST=127.0.0.1
DB_PORT=5432
DB_USER=aisee
DB_PASSWORD=aisee
DB_NAME=saga

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

# Blockchain
HD_WALLET_MASTER_ADDRESS=0xf39Fd6e51aad88F6F4ce6aB8827279cffFb92266
BLOCKCHAIN_RPC_URL=http://188.42.218.164:8545

# Server
SERVER_HOST=0.0.0.0
SERVER_PORT=8080
EOF

Load Environment:

# Load into current shell
source .env

# Verify
echo $JWT_SECRET

6. Run Database Migrations¶

# Build migration tool
cd backend
go build -o bin/migrate cmd/migrate/main.go

# Run migrations
./bin/migrate up

# Verify
PGPASSWORD=aisee psql -U aisee -h 127.0.0.1 -d saga -c "\dt"

Starting Development Environment¶

Option 1: Using Docker (Recommended)¶

Build and Start:

# Build Docker image
make build

# Start container
make restart

# Verify status
make status

Check Logs:

docker logs saga --tail=50 --follow

Option 2: Local Development¶

Start Backend:

cd backend
go run cmd/saga/main.go

Start Frontend (separate terminals):

# Terminal 1: User app
cd frontend/user-app
npm run dev

# Terminal 2: Admin app
cd frontend/admin-app
npm run dev

Access Applications:

User app: http://app.saga.local:3000 (dev server) or http://app.saga.local:8080 (through backend)
Admin app: http://admin.saga.local:3000 (dev server) or http://admin.saga.local:8080 (through backend)
API: http://localhost:8080/api/health

Blockchain Setup¶

VPS Blockchain Node¶

Saga uses production VPS node:

URL: http://188.42.218.164:8545
Network ID: 1337
Type: Anvil (Foundry) testnet

Verify Connection:

# Using curl
curl -X POST -H "Content-Type: application/json" \
  --data '{"jsonrpc":"2.0","method":"eth_blockNumber","params":[],"id":1}' \
  http://188.42.218.164:8545

# Using cast (Foundry)
cast block-number --rpc-url http://188.42.218.164:8545

Deploy Smart Contracts (if needed)¶

# Initialize blockchain with all contracts
make -f makefiles/development.mk vps-init

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

Verify Setup¶

Run Health Checks¶

# Backend health
curl http://localhost:8080/api/health

# Database connection
curl http://localhost:8080/api/health | jq '.database'

# Blockchain connection
curl http://localhost:8080/api/health | jq '.blockchain'

Run Smoke Tests¶

# Quick smoke test (30 seconds)
make smoke

# Should see:
# All smoke tests passed

Test Faucet¶

# Get test USDC
curl -X POST http://localhost:8080/api/faucet/request \
  -H "Content-Type: application/json" \
  -d '{"wallet_address":"0x742d35Cc9Cf3C4C3a3F5d7B5f"}'

🛠️ Development Tools¶

Makefile Commands¶

# View all commands
make help

# Development
make restart         # Smart restart (rebuilds if needed)
make status          # Check system status
make logs            # View container logs

# Testing
make test            # Foundation test suite
make test-all        # Comprehensive testing
make smoke           # Quick smoke tests

# Blockchain
make -f makefiles/development.mk vps-init    # Initialize blockchain
make -f makefiles/development.mk vps-status  # Blockchain status

# Database
make migration-up    # Run migrations
make migration-down  # Rollback migrations

Useful Aliases¶

Add to ~/.bashrc or ~/.zshrc:

# Saga aliases
alias saga-start='cd ~/saga && make restart'
alias saga-logs='docker logs saga --tail=50 --follow'
alias saga-test='cd ~/saga && make test'
alias saga-db='PGPASSWORD=aisee psql -U aisee -h 127.0.0.1 -d saga'

IDE Setup¶

VS Code Extensions:

Go (golang.go)
ESLint (dbaeumer.vscode-eslint)
Prettier (esbenp.prettier-vscode)
Docker (ms-azuretools.vscode-docker)
Thunder Client (rangav.vscode-thunder-client) - for API testing

VS Code 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"
  }
}

Security Setup¶

SSH Keys (for VPS access)¶

# Generate SSH key
ssh-keygen -t ed25519 -C "your_email@example.com"

# Copy to VPS
ssh-copy-id cloud-user@188.42.218.164

# Test connection
ssh cloud-user@188.42.218.164

Git Configuration¶

# Set user
git config user.name "Your Name"
git config user.email "your.email@example.com"

# Set default branch
git config --global init.defaultBranch master

# Auto-rebase on pull
git config pull.rebase true

🐛 Troubleshooting¶

Issue: Port 8080 already in use¶

# Find process using port
lsof -i :8080

# Kill process
kill -9 <PID>

# Or use different port
export SERVER_PORT=8081
make restart

Issue: Database connection failed¶

# Check PostgreSQL is running
systemctl status postgresql

# Start PostgreSQL
sudo systemctl start postgresql

# Reset password
sudo -u postgres psql
ALTER USER aisee WITH PASSWORD 'aisee';

Issue: Blockchain connection timeout¶

# Verify VPS node is accessible
ping 188.42.218.164

# Test RPC endpoint
curl -X POST http://188.42.218.164:8545 \
  -H "Content-Type: application/json" \
  -d '{"jsonrpc":"2.0","method":"eth_blockNumber","params":[],"id":1}'

Issue: Docker build fails¶

# Clean Docker cache
docker system prune -a

# Rebuild from scratch
make build

# Check Docker disk space
docker system df

Next Steps¶

After setup is complete:

Read Documentation:
Architecture Overview
API Documentation
Testing Guide
Start Development:
Create feature branch: git checkout -b feature/your-feature
Make changes
Run tests: make test
Commit: make commit MESSAGE="your message"
Join Team:
Telegram: @AiSeeQ для связи с командой
Daily standups
Code reviews

UnifiedConfig System - Configuration management
Testing Guide - Testing setup and practices
JWT Testing - JWT authentication testing
Deployment Guide - Production deployment

📋 Метаданные¶

Версия: 2.4.82

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

Статус: Published