Development Environment Setup

Prerequisites

Go 1.24+ - Install Go
PostgreSQL 12+ - Install PostgreSQL
Git - Version control

Local Development Setup

1. Clone the Repository

git clone https://github.com/hopekali04/budget365API.git
cd budget365API

2. Install Dependencies

go mod download

3. Database Setup

Option A: Using Docker (Recommended)

# Start PostgreSQL container
docker run --name budget365-postgres \
  -e POSTGRES_DB=budget365 \
  -e POSTGRES_USER=postgres \
  -e POSTGRES_PASSWORD=password \
  -p 5432:5432 \
  -d postgres:15

Option B: Local PostgreSQL

Install PostgreSQL on your system

Create a database:

CREATE DATABASE budget365;
CREATE USER postgres WITH PASSWORD 'password';
GRANT ALL PRIVILEGES ON DATABASE budget365 TO postgres;

4. Environment Configuration

Copy the example environment file and customize it:

cp .env .env.local

Edit .env.local with your specific configuration:

# Server Configuration
SERVER_ADDRESS=:8080

# Database Configuration (adjust as needed)
DATABASE_HOST=localhost
DATABASE_PORT=5432
DATABASE_USER=postgres
DATABASE_PASSWORD=password
DATABASE_DBNAME=budget365
DATABASE_SSLMODE=disable

# Logging Configuration
LOGGING_LEVEL=debug
LOGGING_ENCODING=console  # Use 'console' for development, 'json' for production

5. Run Database Migrations

# Future: When migrations are implemented
# go run cmd/migrate/main.go up

Currently, GORM will auto-migrate tables when the application starts.

6. Start the Application

# Development mode
go run main.go

# Or build and run
go build -o budget365-api main.go
./budget365-api

The API will be available at http://localhost:8080

7. Verify Installation

Test the health endpoint:

curl http://localhost:8080/health

Expected response:

{
  "success": true,
  "message": "Service is healthy",
  "status": "ok",
  "timestamp": "2024-01-15T10:30:00Z",
  "version": "1.0.0"
}

Development Workflow

Code Structure

Follow the established patterns:

Models - Define in /internal/models/
Repositories - Interfaces in /internal/repositories/interfaces.go, implementations in separate files
Services - Interfaces in /internal/services/interfaces.go, implementations in separate files
API Handlers - In /internal/api/
Routes - Configure in /internal/routes/

Running Tests

# Run all tests
go test ./...

# Run tests with coverage
go test -cover ./...

# Run tests for specific package
go test ./internal/services/

# Run integration tests (when available)
go test ./test/...

Code Quality

Linting

# Install golangci-lint
go install github.com/golangci/golangci-lint/cmd/golangci-lint@latest

# Run linter
golangci-lint run

Formatting

# Format code
go fmt ./...

# Import organization
go mod tidy

Database Migrations

When implementing new models or changing existing ones:

Update the model in /internal/models/
GORM will auto-migrate during development
For production, implement proper migrations in /cmd/migrate/

Adding New Features

Define the model in /internal/models/
Create repository interface in /internal/repositories/interfaces.go
Implement repository in /internal/repositories/{feature}_repository.go
Create service interface in /internal/services/interfaces.go
Implement service in /internal/services/{feature}_service.go
Create API handler in /internal/api/{feature}.go
Add routes in /internal/routes/router.go
Write tests for each layer

Environment Variables

Required Variables

Variable	Description	Default	Example
`DATABASE_HOST`	PostgreSQL host	`localhost`	`localhost`
`DATABASE_PORT`	PostgreSQL port	`5432`	`5432`
`DATABASE_USER`	Database user	`postgres`	`postgres`
`DATABASE_PASSWORD`	Database password	`password`	`mypassword`
`DATABASE_DBNAME`	Database name	`budget365`	`budget365`

Optional Variables

Variable	Description	Default
`SERVER_ADDRESS`	Server bind address	`:8080`
`LOGGING_LEVEL`	Log level	`info`
`LOGGING_ENCODING`	Log format	`json`
`AUTH_JWT_SECRET`	JWT secret key	`your-secret-key`

Debugging

Logging

The application uses structured logging with Zap. Logs include: - Request/response details - Database operations - Error context - Request correlation IDs

Database Debugging

Enable GORM debug mode in development:

// In database/db.go, change logger mode
db, err := gorm.Open(postgres.Open(dsn), &gorm.Config{
    Logger: logger.Default.LogMode(logger.Info), // Shows all SQL queries
})

API Testing

Use tools like: - curl - Command line testing - Postman - GUI API testing - httpie - User-friendly command line HTTP client

Example API calls:

# Create user
curl -X POST http://localhost:8080/api/v1/users \
  -H "Content-Type: application/json" \
  -d '{"name":"John Doe","email":"john@example.com","password":"password123"}'

# Get user
curl http://localhost:8080/api/v1/users/1

# List users
curl http://localhost:8080/api/v1/users?page=1&limit=10

Production Deployment

Build

# Build for Linux
GOOS=linux GOARCH=amd64 go build -o budget365-api main.go

# Build with version info
go build -ldflags "-X main.version=1.0.0" -o budget365-api main.go

Docker

Create a Dockerfile:

FROM golang:1.24-alpine AS builder
WORKDIR /app
COPY go.mod go.sum ./
RUN go mod download
COPY . .
RUN go build -o budget365-api main.go

FROM alpine:latest
RUN apk --no-cache add ca-certificates
WORKDIR /root/
COPY --from=builder /app/budget365-api .
CMD ["./budget365-api"]

Environment

Use proper database connections
Set LOGGING_ENCODING=json for structured logs
Configure proper secrets for AUTH_JWT_SECRET
Set appropriate DATABASE_SSLMODE for security

Troubleshooting

Common Issues

Database Connection Failed
Check PostgreSQL is running
Verify connection parameters
Check firewall settings
Port Already in Use
Change SERVER_ADDRESS in environment
Kill existing process: lsof -ti:8080 | xargs kill
Import Errors
Run go mod tidy
Verify Go version compatibility
Migration Issues
Drop and recreate database for development
Check model definitions for errors