# 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

```bash
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:

```bash
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:

```bash
# 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

```sql
CREATE DATABASE b12_sis CHARACTER SET utf8mb4 COLLATE utf8mb4_unicode_ci;
```

### 5. Run the Server

```bash
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

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

```bash
make docs
```

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

## Docker Deployment

### Build Docker Image

```bash
docker build -t b12-backend:latest .
```

### Run with Docker Compose

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

```bash
docker-compose up -d
```

## Kubernetes Deployment

The project includes Helm charts for Kubernetes deployment:

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

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

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

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

## Troubleshooting

### Database Connection Issues

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

2. 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](configuration.md) - Detailed environment configuration
- [Quick Start](quickstart.md) - Make your first API calls
- [API Overview](../api/overview.md) - Understanding the API structure