Installation

This guide covers how to set up the B12 SIS backend for development and production.

Prerequisites

Go: Version 1.23 or higher
MySQL: Version 8.0 or higher
Git: For version control
Make: For running build commands
Docker (optional): For containerized deployment

Development Setup

1. Clone the Repository

git clone https://github.com/trankhanhtoan96/b12-backend.git
cd b12-backend

2. Initial Setup

Run the development setup command which copies the environment file and downloads dependencies:

make dev-setup

This command performs:

Copies .env.example to .env
Runs go mod tidy to download dependencies

3. Configure Environment

Edit the .env file with your settings:

# Database Configuration
DB_MASTER_DSN=user:password@tcp(localhost:3306)/b12_sis?charset=utf8mb4&parseTime=True&loc=Local
DB_SLAVE_DSN=user:password@tcp(localhost:3306)/b12_sis?charset=utf8mb4&parseTime=True&loc=Local

# JWT Configuration
JWT_SECRET=your-secret-key-min-32-characters
JWT_EXPIRES_IN=24h

# Server Configuration
PORT=8080
DEV_MODE=true

4. Create Database

CREATE DATABASE b12_sis CHARACTER SET utf8mb4 COLLATE utf8mb4_unicode_ci;

5. Run the Server

make run

The server will start on http://localhost:8080 and automatically run database migrations.

Available Make Commands

Command	Description
`make dev-setup`	Initial development setup
`make run`	Run the server locally
`make test`	Run all tests
`make test-coverage`	Generate test coverage report
`make docs`	Generate Swagger documentation
`make build`	Build Linux binary
`make deploy`	Deploy to development Kubernetes
`make prod`	Deploy to production

Running Tests

# Run all tests
make test

# Run tests with coverage
make test-coverage

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

# Run tests matching a pattern
go test -v -run TestStudent ./internal/services/

Generating API Documentation

Generate Swagger documentation:

make docs

This creates/updates the Swagger specification in docs/swagger.json.

Docker Deployment

Build Docker Image

docker build -t b12-backend:latest .

Run with Docker Compose

# docker-compose.yml
version: '3.8'
services:
  api:
    image: b12-backend:latest
    ports:
      - "8080:8080"
    environment:
      - DB_MASTER_DSN=user:pass@tcp(mysql:3306)/b12_sis
      - JWT_SECRET=your-secret-key
    depends_on:
      - mysql

  mysql:
    image: mysql:8.0
    environment:
      - MYSQL_ROOT_PASSWORD=root
      - MYSQL_DATABASE=b12_sis
    volumes:
      - mysql_data:/var/lib/mysql

volumes:
  mysql_data:

docker-compose up -d

Kubernetes Deployment

The project includes Helm charts for Kubernetes deployment:

# Deploy to development
make deploy

# Deploy to production
make prod

See the helm/ directory for chart configuration.

Running Background Jobs

The backend can run as an API server or as a job scheduler:

# Run as API server (default)
make run

# Run as job scheduler
DEPLOY_AS_JOB=1 make run

# Run a specific job manually
make run-job JOB=ImportProcessorJob

# List available jobs
make list-jobs

Verifying Installation

After starting the server, verify it’s running:

# Health check
curl http://localhost:8080/api/health

# Expected response
{"status": "ok"}

Troubleshooting

Database Connection Issues

Verify MySQL is running:
```
mysql -u root -p -e "SELECT 1"
```

Check the DSN format in .env:

DB_MASTER_DSN=user:password@tcp(host:port)/database?charset=utf8mb4&parseTime=True&loc=Local

Port Already in Use

Change the port in .env:

PORT=8081

Migration Failures

Migrations run automatically on startup. Check logs for errors and ensure the database user has CREATE/ALTER privileges.

Next Steps

Configuration Guide - Detailed environment configuration
Quick Start - Make your first API calls
API Overview - Understanding the API structure