senke/veza

senke ee3ad8e2f5 [DOC-003] doc: Write development setup guide

2025-12-25 02:54:47 +01:00

16 KiB

Raw Blame History

Veza Backend API - Development Setup Guide

Overview
Prerequisites
Quick Start
Manual Setup
Docker Setup
Project Structure
Configuration
Database Setup
Running the Application
Development Workflow
Testing
Debugging
Development Tools
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:

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

go version
# Should output: go version go1.23.x ...

PostgreSQL

Version: PostgreSQL 12 or higher (15+ recommended)

Installation:

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

psql --version
# Should output: psql (PostgreSQL) 15.x ...

Redis (Optional but Recommended)

Version: Redis 6 or higher

Installation:

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

redis-cli ping
# Should output: PONG

Optional Software

Docker and Docker Compose

For containerized development:

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

go install github.com/cosmtrek/air@latest

golang-migrate

For database migrations:

# Install migrate tool
go install -tags 'postgres' github.com/golang-migrate/migrate/v4/cmd/migrate@latest

Make

For running common tasks:

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

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

# From project root
docker-compose up -d

# Check logs
docker-compose logs -f backend-api

Manual Setup

1. Clone Repository

git clone <repository-url>
cd veza/veza-backend-api

2. Install Dependencies

# Download Go modules
go mod download

# Tidy dependencies
go mod tidy

3. Create Environment File

# 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

# 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

# Using migrate tool
migrate -path ./migrations -database "$DATABASE_URL" up

# Or using Make
make migrate-up

6. Build Application

# Build binary
make build

# Or manually
go build -o bin/veza-backend-api ./cmd/api/main.go

7. Run Application

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

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

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

# 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

# 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

# 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

# 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)

# If seed scripts exist
go run scripts/seed.go

Running the Application

Development Mode

With Hot Reload (Air)

# 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

# Build and run
make run

# Or manually
go run ./cmd/api/main.go

# Or run binary
./bin/veza-backend-api

Verify Application

# Health check
curl http://localhost:8080/healthz

# API endpoint
curl http://localhost:8080/api/v1/tracks

Common Make Commands

# 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

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

# Run all tests
make test

# Run specific test
go test ./internal/services/... -v

# Run with coverage
make test-coverage

4. Check Code Quality

# Format code
make fmt

# Run linter
make lint

# Check for security issues
go vet ./...

5. Commit Changes

git add .
git commit -m "feat: add new feature"

6. Push and Create PR

git push origin feature/my-feature
# Create pull request on GitHub/GitLab

Testing

Unit Tests

# 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

# Run integration tests
go test ./tests/... -v

# Run with database
DATABASE_URL=postgres://... go test ./tests/integration/...

Test Coverage

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

# 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)

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

{
  "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:

export LOG_LEVEL=DEBUG
export LOG_FORMAT=text

View logs:

# 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

Check database connection:
```
psql "$DATABASE_URL" -c "SELECT 1;"
```
Check Redis connection:
```
redis-cli ping
```
Verify environment variables:
```
env | grep -E 'DATABASE|JWT|APP_ENV'
```
Check application health:
```
curl http://localhost:8080/healthz
```

Development Tools

Code Generation

Generate Swagger Documentation

# Install swag
go install github.com/swaggo/swag/cmd/swag@latest

# Generate docs
swag init -g cmd/api/main.go

Generate Mock Services

# 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

# PostgreSQL client
psql "$DATABASE_URL"

# Redis client
redis-cli

# Database migrations
migrate -path ./migrations -database "$DATABASE_URL" version

API Testing

Using curl

# 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

# 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

# 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

# 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

# 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

# Clean module cache
go clean -modcache

# Download dependencies
go mod download

# Tidy modules
go mod tidy

Migration Errors

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

Read the API Documentation: See docs/API_DOCUMENTATION.md
Explore the Codebase: Start with cmd/api/main.go
Run the Test Suite: make test
Check out Example Code: Look at existing handlers and services
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

16 KiB Raw Blame History

Veza Backend API - Development Setup Guide

Table of Contents

Overview

Prerequisites

Required Software

Go

PostgreSQL

Redis (Optional but Recommended)

Optional Software

Docker and Docker Compose

Air (Hot Reload)

golang-migrate

Make

Quick Start

Automated Setup Script

Docker Quick Start

Manual Setup

1. Clone Repository

2. Install Dependencies

3. Create Environment File

4. Setup Database

5. Run Migrations

6. Build Application

7. Run Application

Docker Setup

Using Docker Compose

Docker Compose Services

Environment Variables for Docker

Project Structure

Configuration

Environment Variables

Required Variables

Development Variables

Configuration Files

Database Setup

Create Database

Run Migrations

Seed Database (Optional)

Running the Application

Development Mode

With Hot Reload (Air)

Without Hot Reload

Verify Application

Common Make Commands

Development Workflow

1. Create Feature Branch

2. Make Changes

3. Run Tests

4. Check Code Quality

5. Commit Changes

6. Push and Create PR

Testing

Unit Tests

Integration Tests

Test Coverage

Test Database

Debugging

Using Delve (Go Debugger)

VS Code Debugging

Logging

Common Debugging Tips

Development Tools

Code Generation

Generate Swagger Documentation

Generate Mock Services

Database Tools

Database GUI Clients

CLI Tools

API Testing

Using curl

Using HTTPie

Using Postman

Performance Profiling

Troubleshooting

Common Issues

Database Connection Failed

Port Already in Use

Go Module Issues

Migration Errors

16 KiB

Raw Blame History