senke/veza
1
0
Fork 0
Code Issues Pull requests Projects Releases Packages Wiki Activity Actions

[DOC-003] doc: Write development setup guide

Browse source
This commit is contained in:
senke 2025-12-25 02:54:47 +01:00
parent 504dc73bad
commit 39a8de5ac5
2 changed files with 908 additions and 6 deletions
Show stats Download patch file Download diff file Expand all files Collapse all files

28
VEZA_COMPLETE_MVP_TODOLIST.json
View file

@ -10988,8 +10988,24 @@
"description": "Document local development environment setup",
"owner": "devops",
"estimated_hours": 4,
"status": "todo",
"files_involved": [],
"status": "completed",
"completion": {
"completed_at": "2025-12-25T01:54:31Z",
"actual_hours": 3.5,
"commits": [],
"files_changed": [
"veza-backend-api/docs/DEVELOPMENT_SETUP_GUIDE.md"
],
"notes": "Created comprehensive development setup guide covering all aspects of local development. Documentation includes: Overview and prerequisites (required and optional software), Quick start (automated setup script, Docker quick start), Manual setup (step-by-step installation, environment configuration, database setup), Docker setup (Docker Compose services, environment variables), Project structure (detailed directory layout and organization), Configuration (environment variables, configuration files), Database setup (creation, migrations, seeding), Running the application (development mode, hot reload, verification), Development workflow (feature branches, testing, code quality, commits), Testing (unit tests, integration tests, test coverage, test database), Debugging (Delve debugger, VS Code debugging, logging, common tips), Development tools (code generation, database tools, API testing, performance profiling), Troubleshooting (common issues, getting help).",
"issues_encountered": []
},
"files_involved": [
{
"path": "veza-backend-api/docs/DEVELOPMENT_SETUP_GUIDE.md",
"action": "create",
"reason": "Comprehensive development setup guide for local environment"
}
],
"implementation_steps": [
{
"step": 1,
@ -11435,11 +11451,11 @@
]
},
"progress_tracking": {
"completed": 148,
"completed": 149,
"in_progress": 0,
"todo": 131,
"todo": 130,
"blocked": 0,
"last_updated": "2025-12-25T01:51:57Z",
"completion_percentage": 55.43071161048689
"last_updated": "2025-12-25T01:54:31Z",
"completion_percentage": 55.80524344569288
}
}

886
veza-backend-api/docs/DEVELOPMENT_SETUP_GUIDE.md Normal file
View file

@ -0,0 +1,886 @@
# Veza Backend API - Development Setup Guide
## Table of Contents
1. [Overview](#overview)
2. [Prerequisites](#prerequisites)
3. [Quick Start](#quick-start)
4. [Manual Setup](#manual-setup)
5. [Docker Setup](#docker-setup)
6. [Project Structure](#project-structure)
7. [Configuration](#configuration)
8. [Database Setup](#database-setup)
9. [Running the Application](#running-the-application)
10. [Development Workflow](#development-workflow)
11. [Testing](#testing)
12. [Debugging](#debugging)
13. [Development Tools](#development-tools)
14. [Troubleshooting](#troubleshooting)
## Overview
This guide will help you set up a local development environment for the Veza Backend API. The API is built with Go 1.23+ using the Gin web framework, PostgreSQL for data storage, and Redis for caching.
## Prerequisites
### Required Software
#### Go
**Version:** Go 1.23 or higher
**Installation:**
```bash
# Ubuntu/Debian
sudo apt update
sudo apt install golang-go
# Fedora/RHEL
sudo dnf install golang
# macOS
brew install go
# Windows
# Download from https://golang.org/dl/
# Or use Chocolatey: choco install golang
```
**Verify Installation:**
```bash
go version
# Should output: go version go1.23.x ...
```
#### PostgreSQL
**Version:** PostgreSQL 12 or higher (15+ recommended)
**Installation:**
```bash
# Ubuntu/Debian
sudo apt install postgresql postgresql-contrib
# Fedora/RHEL
sudo dnf install postgresql postgresql-server
# macOS
brew install postgresql@15
brew services start postgresql@15
# Windows
# Download from https://www.postgresql.org/download/windows/
```
**Verify Installation:**
```bash
psql --version
# Should output: psql (PostgreSQL) 15.x ...
```
#### Redis (Optional but Recommended)
**Version:** Redis 6 or higher
**Installation:**
```bash
# Ubuntu/Debian
sudo apt install redis-server
# Fedora/RHEL
sudo dnf install redis
# macOS
brew install redis
brew services start redis
# Windows
# Download from https://github.com/microsoftarchive/redis/releases
```
**Verify Installation:**
```bash
redis-cli ping
# Should output: PONG
```
### Optional Software
#### Docker and Docker Compose
For containerized development:
```bash
# Ubuntu/Debian
sudo apt install docker.io docker-compose
# Fedora/RHEL
sudo dnf install docker docker-compose
# macOS
brew install docker docker-compose
# Windows
# Download Docker Desktop from https://www.docker.com/products/docker-desktop
```
#### Air (Hot Reload)
For automatic code reloading during development:
```bash
go install github.com/cosmtrek/air@latest
```
#### golang-migrate
For database migrations:
```bash
# Install migrate tool
go install -tags 'postgres' github.com/golang-migrate/migrate/v4/cmd/migrate@latest
```
#### Make
For running common tasks:
```bash
# Ubuntu/Debian
sudo apt install build-essential
# Fedora/RHEL
sudo dnf install make
# macOS (usually pre-installed)
# Windows: Use Chocolatey or install from http://gnuwin32.sourceforge.net/packages/make.htm
```
## Quick Start
### Automated Setup Script
The fastest way to get started:
```bash
# Navigate to backend API directory
cd veza-backend-api
# Run setup script
chmod +x scripts/setup-dev.sh
./scripts/setup-dev.sh
```
This script will:
- Check for required software (Go, PostgreSQL, Redis)
- Create `.env` file from template
- Create database if it doesn't exist
- Install Go dependencies
- Build the application
### Docker Quick Start
If you prefer Docker:
```bash
# From project root
docker-compose up -d
# Check logs
docker-compose logs -f backend-api
```
## Manual Setup
### 1. Clone Repository
```bash
git clone <repository-url>
cd veza/veza-backend-api
```
### 2. Install Dependencies
```bash
# Download Go modules
go mod download
# Tidy dependencies
go mod tidy
```
### 3. Create Environment File
```bash
# Copy example environment file
cp .env.example .env
# Or create manually
cat > .env << EOF
# Database
DATABASE_URL=postgres://veza:password@localhost:5432/veza_dev?sslmode=disable
# Security
JWT_SECRET=your-super-secret-jwt-key-minimum-32-characters-long
JWT_EXPIRY=24h
# Application
APP_ENV=development
API_PORT=8080
LOG_LEVEL=DEBUG
LOG_FORMAT=text
# Redis (Optional)
REDIS_URL=redis://localhost:6379
# Services
CHAT_SERVER_URL=http://localhost:8081
STREAM_SERVER_URL=http://localhost:8082
EOF
```
### 4. Setup Database
```bash
# Create PostgreSQL user and database
sudo -u postgres psql << EOF
CREATE USER veza WITH PASSWORD 'password';
CREATE DATABASE veza_dev OWNER veza;
GRANT ALL PRIVILEGES ON DATABASE veza_dev TO veza;
\q
EOF
# Or using createdb (if user exists)
createdb -U veza veza_dev
```
### 5. Run Migrations
```bash
# Using migrate tool
migrate -path ./migrations -database "$DATABASE_URL" up
# Or using Make
make migrate-up
```
### 6. Build Application
```bash
# Build binary
make build
# Or manually
go build -o bin/veza-backend-api ./cmd/api/main.go
```
### 7. Run Application
```bash
# Run directly
./bin/veza-backend-api
# Or using Make
make run
# Or with hot reload (if Air is installed)
air
```
## Docker Setup
### Using Docker Compose
The project includes a `docker-compose.yml` for local development:
```bash
# Start all services (PostgreSQL, Redis, Backend API)
docker-compose up -d
# View logs
docker-compose logs -f backend-api
# Stop services
docker-compose down
# Rebuild and restart
docker-compose up -d --build
```
### Docker Compose Services
- **postgres**: PostgreSQL database on port 5432
- **redis**: Redis cache on port 6379
- **backend-api**: Go API on port 8080
### Environment Variables for Docker
Create `.env` file in project root:
```bash
POSTGRES_DB=veza_dev
POSTGRES_USER=veza
POSTGRES_PASSWORD=password
REDIS_PASSWORD=
JWT_SECRET=your-super-secret-jwt-key-minimum-32-characters-long
```
## Project Structure
```
veza-backend-api/
├── cmd/
│ └── api/
│ └── main.go # Application entry point
├── internal/
│ ├── api/ # HTTP routes and router configuration
│ ├── core/ # Business logic (auth, track, marketplace)
│ │ ├── auth/ # Authentication core
│ │ ├── track/ # Track management core
│ │ ├── marketplace/ # Marketplace core
│ │ └── social/ # Social features core
│ ├── config/ # Configuration management
│ ├── database/ # Database connection and migrations
│ ├── handlers/ # HTTP request handlers
│ ├── middleware/ # HTTP middleware (auth, CORS, rate limiting)
│ ├── models/ # GORM data models
│ ├── repositories/ # Data access layer
│ ├── services/ # Business services
│ ├── workers/ # Background job workers
│ ├── validators/ # Input validation
│ └── utils/ # Utility functions
├── migrations/ # SQL migration files
├── tests/ # Integration tests
├── docs/ # Documentation
├── scripts/ # Utility scripts
├── Makefile # Common tasks
├── go.mod # Go module definition
├── go.sum # Go module checksums
└── .env # Environment variables (not in git)
```
## Configuration
### Environment Variables
#### Required Variables
```bash
# Database connection
DATABASE_URL=postgres://user:password@host:5432/dbname?sslmode=disable
# JWT secret (minimum 32 characters)
JWT_SECRET=your-super-secret-jwt-key-minimum-32-characters-long
# Application environment
APP_ENV=development # development|staging|production
```
#### Development Variables
```bash
# Logging
LOG_LEVEL=DEBUG # DEBUG|INFO|WARN|ERROR
LOG_FORMAT=text # text|json
# Server
API_PORT=8080
HANDLER_TIMEOUT=30s
# Redis (optional)
REDIS_URL=redis://localhost:6379
# Services
CHAT_SERVER_URL=http://localhost:8081
STREAM_SERVER_URL=http://localhost:8082
# Uploads
UPLOAD_DIR=./uploads
MAX_CONCURRENT_UPLOADS=10
# ClamAV (optional)
ENABLE_CLAMAV=false # Set to false for local development
CLAMAV_REQUIRED=false
```
### Configuration Files
- `.env`: Local environment variables (not committed to git)
- `.env.example`: Example environment file (committed to git)
- `config/`: Configuration files for different environments
## Database Setup
### Create Database
```bash
# Using psql
sudo -u postgres psql
CREATE DATABASE veza_dev;
CREATE USER veza WITH PASSWORD 'password';
GRANT ALL PRIVILEGES ON DATABASE veza_dev TO veza;
\q
# Or using createdb
createdb -U veza veza_dev
```
### Run Migrations
```bash
# Using migrate tool
migrate -path ./migrations -database "$DATABASE_URL" up
# Check migration status
migrate -path ./migrations -database "$DATABASE_URL" version
# Rollback last migration
migrate -path ./migrations -database "$DATABASE_URL" down 1
```
### Seed Database (Optional)
```bash
# If seed scripts exist
go run scripts/seed.go
```
## Running the Application
### Development Mode
#### With Hot Reload (Air)
```bash
# Install Air if not already installed
go install github.com/cosmtrek/air@latest
# Run with hot reload
air
# Or create .air.toml config file
air init
air
```
#### Without Hot Reload
```bash
# Build and run
make run
# Or manually
go run ./cmd/api/main.go
# Or run binary
./bin/veza-backend-api
```
### Verify Application
```bash
# Health check
curl http://localhost:8080/healthz
# API endpoint
curl http://localhost:8080/api/v1/tracks
```
### Common Make Commands
```bash
# Build application
make build
# Run application
make run
# Run tests
make test
# Run tests with coverage
make test-coverage
# Run linter
make lint
# Format code
make fmt
# Run migrations
make migrate-up
make migrate-down
# Clean build artifacts
make clean
```
## Development Workflow
### 1. Create Feature Branch
```bash
git checkout -b feature/my-feature
```
### 2. Make Changes
- Write code following Go best practices
- Follow project structure conventions
- Add tests for new functionality
### 3. Run Tests
```bash
# Run all tests
make test
# Run specific test
go test ./internal/services/... -v
# Run with coverage
make test-coverage
```
### 4. Check Code Quality
```bash
# Format code
make fmt
# Run linter
make lint
# Check for security issues
go vet ./...
```
### 5. Commit Changes
```bash
git add .
git commit -m "feat: add new feature"
```
### 6. Push and Create PR
```bash
git push origin feature/my-feature
# Create pull request on GitHub/GitLab
```
## Testing
### Unit Tests
```bash
# Run all unit tests
go test ./...
# Run tests in specific package
go test ./internal/services/...
# Run with verbose output
go test -v ./...
# Run specific test
go test -v ./internal/services -run TestUserService
```
### Integration Tests
```bash
# Run integration tests
go test ./tests/... -v
# Run with database
DATABASE_URL=postgres://... go test ./tests/integration/...
```
### Test Coverage
```bash
# Generate coverage report
go test -cover ./...
# Generate HTML coverage report
go test -coverprofile=coverage.out ./...
go tool cover -html=coverage.out -o coverage.html
```
### Test Database
For integration tests, use a separate test database:
```bash
# Create test database
createdb -U veza veza_test
# Set test database URL
export DATABASE_URL=postgres://veza:password@localhost:5432/veza_test?sslmode=disable
# Run tests
go test ./tests/...
```
## Debugging
### Using Delve (Go Debugger)
```bash
# Install Delve
go install github.com/go-delve/delve/cmd/dlv@latest
# Debug application
dlv debug ./cmd/api/main.go
# Or attach to running process
dlv attach <pid>
```
### VS Code Debugging
Create `.vscode/launch.json`:
```json
{
"version": "0.2.0",
"configurations": [
{
"name": "Launch API",
"type": "go",
"request": "launch",
"mode": "debug",
"program": "${workspaceFolder}/cmd/api/main.go",
"env": {
"DATABASE_URL": "postgres://veza:password@localhost:5432/veza_dev?sslmode=disable",
"JWT_SECRET": "your-secret-key",
"APP_ENV": "development"
}
}
]
}
```
### Logging
Enable debug logging:
```bash
export LOG_LEVEL=DEBUG
export LOG_FORMAT=text
```
View logs:
```bash
# If running directly
./bin/veza-backend-api
# If using Docker
docker-compose logs -f backend-api
# If using systemd
journalctl -u veza-backend-api -f
```
### Common Debugging Tips
1. **Check database connection:**
```bash
psql "$DATABASE_URL" -c "SELECT 1;"
```
2. **Check Redis connection:**
```bash
redis-cli ping
```
3. **Verify environment variables:**
```bash
env | grep -E 'DATABASE|JWT|APP_ENV'
```
4. **Check application health:**
```bash
curl http://localhost:8080/healthz
```
## Development Tools
### Code Generation
#### Generate Swagger Documentation
```bash
# Install swag
go install github.com/swaggo/swag/cmd/swag@latest
# Generate docs
swag init -g cmd/api/main.go
```
#### Generate Mock Services
```bash
# Install mockgen
go install github.com/golang/mock/mockgen@latest
# Generate mocks
mockgen -source=internal/services/user_service.go -destination=internal/mocks/user_service_mock.go
```
### Database Tools
#### Database GUI Clients
- **pgAdmin**: https://www.pgadmin.org/
- **DBeaver**: https://dbeaver.io/
- **TablePlus**: https://tableplus.com/
#### CLI Tools
```bash
# PostgreSQL client
psql "$DATABASE_URL"
# Redis client
redis-cli
# Database migrations
migrate -path ./migrations -database "$DATABASE_URL" version
```
### API Testing
#### Using curl
```bash
# Health check
curl http://localhost:8080/healthz
# Get tracks
curl http://localhost:8080/api/v1/tracks
# Login
curl -X POST http://localhost:8080/api/v1/auth/login \
-H "Content-Type: application/json" \
-d '{"email":"user@example.com","password":"password"}'
```
#### Using HTTPie
```bash
# Install HTTPie
pip install httpie
# Make requests
http GET http://localhost:8080/api/v1/tracks
http POST http://localhost:8080/api/v1/auth/login email=user@example.com password=password
```
#### Using Postman
Import the API collection from `docs/postman/veza-api.json` (if available).
### Performance Profiling
```bash
# Enable pprof
export ENABLE_PPROF=true
# Access profiler
go tool pprof http://localhost:8080/debug/pprof/profile
go tool pprof http://localhost:8080/debug/pprof/heap
```
## Troubleshooting
### Common Issues
#### Database Connection Failed
```bash
# Check PostgreSQL is running
sudo systemctl status postgresql
# Check connection
psql "$DATABASE_URL" -c "SELECT 1;"
# Verify DATABASE_URL format
echo $DATABASE_URL
```
#### Port Already in Use
```bash
# Find process using port 8080
lsof -i :8080
# or
netstat -tulpn | grep 8080
# Kill process
kill -9 <pid>
# Or change port in .env
API_PORT=8081
```
#### Go Module Issues
```bash
# Clean module cache
go clean -modcache
# Download dependencies
go mod download
# Tidy modules
go mod tidy
```
#### Migration Errors
```bash
# Check migration status
migrate -path ./migrations -database "$DATABASE_URL" version
# Force version (if needed)
migrate -path ./migrations -database "$DATABASE_URL" force <version>
# Rollback and retry
migrate -path ./migrations -database "$DATABASE_URL" down 1
migrate -path ./migrations -database "$DATABASE_URL" up
```
### Getting Help
- **Documentation**: See `docs/` directory
- **API Documentation**: http://localhost:8080/swagger/index.html
- **Issues**: Create an issue on GitHub
- **Team Chat**: Ask in team Slack/Discord
## Next Steps
After setting up your development environment:
1. **Read the API Documentation**: See `docs/API_DOCUMENTATION.md`
2. **Explore the Codebase**: Start with `cmd/api/main.go`
3. **Run the Test Suite**: `make test`
4. **Check out Example Code**: Look at existing handlers and services
5. **Join the Team**: Get familiar with team workflows and conventions
## Additional Resources
- **Go Documentation**: https://golang.org/doc/
- **Gin Framework**: https://gin-gonic.com/docs/
- **GORM Documentation**: https://gorm.io/docs/
- **PostgreSQL Documentation**: https://www.postgresql.org/docs/
- **Redis Documentation**: https://redis.io/documentation