Agenda

What We'll Cover Today

1. Project Overview - What is this project?
2. Prerequisites - What you need to get started
3. Environment Setup - Configuration & variables
4. Database Setup - Migrations & seeding
5. Running the Project - Local & Docker
6. Development Workflow - Daily tasks
7. Testing - How to test your code
8. Monitoring & Observability - Tools & dashboards
9. Code Generation - Creating new features
10. Troubleshooting - Common issues & solutions

Project Overview

What is This Project?

• Type: RESTful API built with Go (Golang)
• Architecture: Domain-Driven Design (DDD)
• Framework: Echo web framework
• Database: MySQL with GORM
• Features:
  • JWT Authentication
  • API Versioning (v1, v2)
  • Swagger Documentation
  • Comprehensive Monitoring
  • Distributed Tracing
  • Metrics Collection

Key Technologies

Prerequisites - System Requirements

Required Software

Verify Installation

go version          # Should show 1.19+
docker --version    # Should show Docker 27+
docker compose version  # Should show v2.x
make --version      # Should show make version

Prerequisites - Development Tools (Optional)

Recommended Tools

VS Code Extensions (if using VS Code)

• Go extension
• Docker extension
• YAML extension
• Markdown extension

Step 1 - Clone the Repository

Getting the Code

# Clone the repository
git clone <repository-url>
cd go-api

# Verify you're on the correct branch
git branch

# If needed, switch to development branch
git checkout release

Project Structure Overview

go-api/
├── cmd/              # Application entry points
├── config/           # Configuration management
├── internal/         # Private application code
│   ├── api/         # API handlers & routes
│   ├── domain/      # Business logic (DDD)
│   ├── model/       # Data models
│   └── middleware/  # HTTP middleware
├── database/        # Migrations & seeders
├── docker/          # Docker configurations
└── tests/           # Test files

Step 2 - Environment Configuration

Quick Setup (Recommended)

# Automated setup with interactive prompts
./scripts/setup-env.sh

This script will:

• ✅ Create .env file
• ✅ Prompt for required values
• ✅ Validate configuration
• ✅ Set up default values

Step 2 - Environment Configuration (Manual)

Manual Setup Process

# 1. Copy the example file
cp .env.example .env

# 2. Edit with your preferred editor
nano .env
# or
code .env

Local Development Environment Variables

App Configuration:

ENVIRONMENT=local
DOCKER_NETWORK_MODE=bridge
PORT=8085
HOST=0.0.0.0

Database Configuration:

DB_HOST=classera_db
DB_PORT=3306
DB_USER=your_database_user
DB_PASSWORD=your_secure_password
DB_NAME=classera_g2
DB_DRIVER=mysql
DB_MAX_IDLE_CONNS=10
DB_MAX_OPEN_CONNS=100

Step 2 - Environment Configuration (JWT & Security)

JWT & Security Settings

# JWT Configuration
JWT_SECRET=your-secret-key
JWT_PASSPHRASE=your-passphrase
JWT_ENCRYPT_METHOD=AES-128-CBC
JWT_IV=1122334455667788

# Security Settings
SECURITY_IV=your_security_iv
SECURITY_PASSPHRASE=your_security_passphrase
SECURITY_HASH_STRING=your_hash_string
SECURITY_SALT=your_salt
SECURITY_CIPHER_SEED=your_cipher_seed
SECURITY_KEY=your_security_key
SECURITY_ENCRYPTION_METHOD=your_encryption_method
SECURITY_SUFFIX=your_suffix

Telemetry Configuration

TELEMETRY_ENABLED=true
TELEMETRY_SERVICE_NAME=golang-blueprint
TELEMETRY_SERVICE_VERSION=1.0.0
TELEMETRY_TRACING_ENABLED=true
JAEGER_ENDPOINT=localhost:4318

Step 3 - Database Setup

Option A: Using Docker (Recommended)

# Start only the database container
docker-compose -f docker-compose.local.yml up -d db

# Verify database is running
docker ps | grep db

Option B: Local MySQL

# Start MySQL service
sudo systemctl start mysql

# Create database
mysql -u root -p
CREATE DATABASE golang_blueprint;
EXIT;

Verify Connection

# Test database connection
mysql -h localhost -P 3306 -u root -p -e "SELECT 1;"

Step 4 - Run Database Migrations

Using Custom CLI (Recommended for Development)

# Build the CLI tool
make build-cli

# Create a new migration
./bin/cli migrate create create_users_table

# Run all migrations
./bin/cli migrate up

# Check migration status
./bin/cli migrate status

Using Makefile Commands

# Run migrations (requires Docker container)
make migrate

# Create new migration
make migrate-create name=create_products

# Check status
make migrate-status

Step 5 - Seed the Database

Running Seeders

# Seed all tables
make seed

# Seed specific table
make seed-table table=users

# Check seeder status
make seed-status

# Force re-run all seeders
make seed-force

Seeder Features

• ✅ Automatic CSV file detection
• ✅ UPSERT operations (no duplicates)
• ✅ Tracking system (knows what's been seeded)
• ✅ Force re-run option

Step 6 - Running the Application Locally

Prerequisites

• ✅ Ensure Docker is installed and running
• ✅ Environment file (.env) is configured

Start Local Environment

# Start all services (app, database, monitoring)
make run-app-local

# This may take time on first run due to DB dump import

What This Does

• Starts MySQL database container (classera_db)
• Imports database dump (first time only)
• Starts API application
• Starts monitoring services (Prometheus, Grafana, Jaeger)

View Logs

# View application logs
docker-compose -f docker-compose.local.yml logs -f app

# View database logs
docker-compose -f docker-compose.local.yml logs -f db

Step 7 - Connect Frontend Docker App to Same Database

Why Connect Frontend to Same DB?

• Share the same database between API and Frontend
• Test full-stack integration locally
• Use existing seeded data

Step 1: Add Network to Frontend docker-compose.yml

networks:
  api-30_classera-network:
    name: api-30_classera-network
    external: true

Step 2: Configure Frontend Service

services:
  classera-web:
    # ... other config
    networks:
      - api-30_classera-network

Frontend Database Configuration

Step 3: Update Frontend .env File

In your frontend application's .env file:

# Database Configuration
DB_HOST=classera_db
DB_PORT=3306
DB_USER=MrRDS
DB_PASSWORD=C1assnaPr0dD
DB_NAME=classera_g2

Important Notes

• ✅ Use classera_db as DB_HOST (Docker service name)
• ✅ Both API and Frontend must be on the same Docker network
• ✅ Network name: api-30_classera-network

Verify Connection

# Check if both containers are on same network
docker network inspect api-30_classera-network

# Test database connection from frontend container
docker exec -it classera-web-container mysql -h classera_db -u MrRDS -p

Step 6 - Verify Application is Running

Check Application Health

# Health check endpoint
curl http://localhost:8085/health

# Or visit in browser
http://localhost:8085/health

Expected Response

{
  "status": "healthy",
  "timestamp": "2024-01-15T10:30:00Z"
}

Access Points

SSH Tunnels - Connect to Production/Staging DB

Why Use SSH Tunnels?

• Debug production/staging issues locally
• Access remote databases securely
• Test queries against real data
• Trace issues without direct DB access

Available Tunnel Commands

make tunnel-stg-up
make tunnel-stg-down

make tunnel-me-up
make tunnel-me-down

make tunnel-oman-up
make tunnel-oman-down

make tunnel-pk-up
make tunnel-pk-down

SSH Tunnel Configuration

Step 1: Create Environment File

Create environment file for the environment you want to connect to:

# For staging
cp .env.example .env.stg

# For Middle East production
cp .env.example .env.me

# For Oman production
cp .env.example .env.oman

# For Pakistan production
cp .env.example .env.pk

Step 2: Configure Tunnel Variables

Edit the environment file and add:

SSH_HOST=your-server-ip
REMOTE_DB_HOST=10.0.0.5
REMOTE_DB_PORT=3306
LOCAL_TUNNEL_PORT=3307

⚠️ Important: Use different LOCAL_TUNNEL_PORT for each environment!

Using SSH Tunnels

Step 3: Start the Tunnel

# For staging
make tunnel-stg-up

# For Middle East production
make tunnel-me-up

# For Oman production
make tunnel-oman-up

# For Pakistan production
make tunnel-pk-up

Step 4: Update Local .env

Update your local .env to use the tunnel:

DB_HOST=localhost
DB_PORT=3307  # Your LOCAL_TUNNEL_PORT
DB_USER=MrRDS
DB_PASSWORD=C1assnaPr0dD
DB_NAME=classera_g2

Step 5: Connect to Database

# Connect via tunnel
mysql -h localhost -P 3307 -u MrRDS -p

# Or use your application
make run-app-local

SSH Tunnel Management

Check Tunnel Status

# Check if tunnel is running
ps aux | grep "ssh -N -f -L"

# Test connection
mysql -h localhost -P 3307 -u MrRDS -p -e "SELECT 1;"

Stop Tunnel

# Stop specific tunnel
make tunnel-stg-down
make tunnel-me-down

# Stop all tunnels
make tunnel-all-down

Manual SSH Tunnel (Alternative)

# Manual command format
ssh -N -f -L {local_port}:{remote_db_host}:{remote_db_port} ubuntu@{server_ip}

# Example
ssh -N -f -L 3307:10.0.0.5:3306 [email protected]

# Stop manual tunnel
pkill -f "ssh -N -f -L 3307:10.0.0.5:3306"

Best Practices

• ✅ Always close tunnels when done
• ✅ Use different ports for each environment
• ✅ Never commit .env.stg, .env.me, etc. to Git
• ⚠️ Be careful with production data

Step 7 - Monitoring & Observability

Monitoring Dashboard

Central Monitoring Hub:

Individual Services

Daily Development Workflow

Typical Day-to-Day Tasks

1. Start Your Day:

# Pull latest changes
git pull origin release

# Start services
docker-compose -f docker-compose.local.yml up -d

# Check application status
curl http://localhost:8085/health

2. Create New Feature:

# Create migration
make migrate-create name=add_feature_table

# Edit migration file
# database/migrations/YYYYMMDDHHMMSS_add_feature_table.sql

# Run migration
make migrate

# Generate code (if needed)
go run scripts/generate.go -name product -type model

Code Generation

Generate New Features (DDD Pattern)

Generate Complete Stack (Recommended):

# Generate model + domain + handler (full stack)
go run scripts/generate.go -name product -type model

This generates:

• ✅ internal/model/product.go - Data model
• ✅ internal/domain/product/repository.go - Repository interface & implementation
• ✅ internal/domain/product/service.go - Service interface & implementation
• ✅ internal/api/v1/handler/product/product_handler.go - HTTP handlers (Echo)
• ✅ internal/api/v1/handler/product/product_routes.go - Route registration
• ✅ Registration instructions in tmp/ directory

Other Generation Types

# Generate domain layer only (repository + service)
go run scripts/generate.go -name product -type domain

# Generate handler only
go run scripts/generate.go -name product -type handler

# Generate seeder
go run scripts/generate.go -name product -type seeder

Testing

Running Tests

make test

make test-unit

make test-integration

make test-coverage

API Development

API Versioning

The API uses URL versioning:

• V1: /api/v1/* (Stable)
• V2: /api/v2/* (Beta)

Example Endpoints

# Health check
GET /api/v1/health

# Authentication
POST /api/v1/auth/login
POST /api/v1/auth/register

# Courses
GET /api/v1/courses
GET /api/v1/courses/:id
POST /api/v1/courses

Swagger Documentation

After making API changes:

make swagger

Then visit:

Architecture Overview

Domain-Driven Design (DDD)

Benefits

• ✅ Separation of concerns
• ✅ Testable code
• ✅ Maintainable structure
• ✅ Scalable architecture

Common Makefile Commands

Troubleshooting - Common Issues

# Check if MySQL is running
docker ps | grep db

# Check database credentials
cat .env | grep DB_

# Find process using port
lsof -i :8085

# Kill the process
kill -9 <PID>

# Check status
make migrate-status

# Rollback
make migrate-down

Quick Reference - Setup Checklist

First-Time Setup Checklist

• Install prerequisites (Go, Docker, Make)
• Clone repository
• Copy env.local.example to .env
• Configure environment variables
• Start database: docker-compose up -d db
• Run migrations: make migrate
• Seed database: make seed
• Start application: make run-app-local
• Verify health: curl http://localhost:8085/health
• Access Swagger: http://localhost:8085/swagger/index.html

Summary - Key Takeaways

What We Learned

1. ✅ Setup Process - Environment, database, migrations
2. ✅ Development Workflow - Daily tasks and best practices
3. ✅ Code Structure - DDD architecture and organization
4. ✅ Testing - How to write and run tests
5. ✅ Monitoring - Tools and dashboards available
6. ✅ Troubleshooting - Common issues and solutions

Next Steps

1. Set up your environment using this guide
2. Explore the codebase to understand structure
3. Run the application and test endpoints
4. Create a small feature to practice workflow
5. Ask questions when you need help