Local Setup

Panduan lengkap untuk setup environment development lokal dalam ≤15 menit.

🚀 Quick Start

# 1. Clone repository
git clone https://github.com/your/repo.git
cd repo

# 2. Copy environment file
cp .env.example .env

# 3. Start semua services
task dev:up

# 4. Run backend dengan live reload
task dev:air

# 5. Run Flutter app
cd frontend
flutter pub get
flutter run -d chrome

Setelah langkah di atas, aplikasi sudah berjalan di http://localhost:3000 (frontend) dan http://localhost:8080 (backend)

📁 1. Clone Repository

git clone https://github.com/your/repo.git
cd repo

Struktur folder:

repo/
├── backend/           # Go services
├── frontend/          # Flutter app
├── docker-compose.yml # Dev services
├── Taskfile.yml       # Task definitions
├── .env.example       # Environment template
└── observability/     # LGTM configs

⚙️ 2. Environment Configuration

Copy Environment File

cp .env.example .env

Edit `.env`

# Application
APP_ENV=development
APP_NAME=windsurf-app
APP_PORT=8080

# Database - MySQL
MYSQL_HOST=localhost
MYSQL_PORT=3306
MYSQL_USER=root
MYSQL_PASSWORD=secret
MYSQL_DATABASE=windsurf_db

# Database - MongoDB
MONGO_URI=mongodb://localhost:27017
MONGO_DATABASE=windsurf_mongo

# Redis
REDIS_HOST=localhost
REDIS_PORT=6379
REDIS_PASSWORD=

# JWT
JWT_SECRET=your-super-secret-key-change-in-production
JWT_EXPIRY=24h

# Observability
LOKI_URL=http://localhost:3100
TEMPO_URL=http://localhost:9411
MIMIR_URL=http://localhost:9009
GRAFANA_URL=http://localhost:3000

PENTING: Jangan commit file .env ke git! File ini sudah ada di .gitignore

🐳 3. Start Development Services

Menggunakan Taskfile

# Start semua services (MySQL, MongoDB, Redis, LGTM)
task dev:up

# Lihat logs
task dev:logs

# Stop services
task dev:down

# Restart services
task dev:restart

Manual dengan Docker Compose

# Start services
docker compose up -d

# Check status
docker compose ps

# View logs
docker compose logs -f

# Stop services
docker compose down

# Stop & remove volumes (reset data)
docker compose down -v

Services yang Berjalan

Service	Port	URL	Credentials
MySQL	3306	`localhost:3306`	root / secret
MongoDB	27017	`localhost:27017`	-
Redis	6379	`localhost:6379`	-
Grafana	3000	http://localhost:3000	admin / admin
Loki	3100	http://localhost:3100	-
Tempo	9411	http://localhost:9411	-
Mimir	9009	http://localhost:9009	-

Akses Grafana di http://localhost:3000 (admin/admin) untuk melihat logs, metrics, dan traces

🔧 4. Backend Setup (Go)

Install Dependencies

cd backend

# Download Go modules
go mod download

# Install dev tools
go install github.com/cosmtrek/air@latest
go install github.com/golangci/golangci-lint/cmd/golangci-lint@latest

Database Migration

# Run migrations
task db:migrate:up

# Seed data
task db:seed

# Reset database (drop + migrate + seed)
task db:reset

Run Backend

Live Reload (Recommended)
Standard Run
Build & Run

# Menggunakan Air - auto reload on file change
task dev:air

# Atau manual
cd backend
air

Backend running di http://localhost:8080 dengan auto-reload

# Run tanpa live reload
cd backend
go run cmd/api/main.go

# Build binary
task build

# Run binary
./bin/api

Verify Backend

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

# Expected response:
# {"status":"ok","timestamp":"2024-01-01T00:00:00Z"}

# API docs (Swagger)
open http://localhost:8080/swagger/index.html

📱 5. Frontend Setup (Flutter)

Install Dependencies

cd frontend

# Get Flutter packages
flutter pub get

# Generate code (if using freezed/json_serializable)
flutter pub run build_runner build --delete-conflicting-outputs

Environment Configuration

Edit lib/core/config/env.dart:

class Env {
  static const String apiBaseUrl = String.fromEnvironment(
    'API_BASE_URL',
    defaultValue: 'http://localhost:8080',
  );
  
  static const String environment = String.fromEnvironment(
    'ENVIRONMENT',
    defaultValue: 'development',
  );
}

Run Flutter App

Web (Chrome)
iOS Simulator
Android Emulator
Desktop (macOS)

flutter run -d chrome

App running di http://localhost:3000

# List devices
flutter devices

# Run on iOS
flutter run -d "iPhone 15 Pro"

# Start emulator
emulator -avd Pixel_7_API_34

# Run on Android
flutter run -d emulator-5554

flutter run -d macos

Verify Frontend

Buka browser di http://localhost:3000
Login dengan credentials default:
- Email: [email protected]
- Password: admin123

🧪 6. Verify Setup

Run Tests

# Backend tests
cd backend
go test ./... -v -cover

# Frontend tests
cd frontend
flutter test

Check Services Health

# All services health check
task health:check

Expected output:

✓ MySQL      : Connected
✓ MongoDB    : Connected
✓ Redis      : Connected
✓ Backend API: Running (http://localhost:8080)
✓ Frontend   : Running (http://localhost:3000)
✓ Grafana    : Running (http://localhost:3000)

📊 7. Access Observability

Grafana Dashboards

Buka http://localhost:3000
Login: admin / admin
Navigate ke Dashboards → Browse
Pilih dashboard:
- Application Metrics - CPU, memory, request rate
- API Performance - Response time, error rate
- Database Metrics - Query performance, connections

Loki (Logs)

Di Grafana, buka Explore
Pilih data source: Loki
Query logs:
```
{app="backend"} |= "error"
```

Tempo (Traces)

Di Grafana, buka Explore
Pilih data source: Tempo
Search traces by service atau trace ID

🔄 8. Development Workflow

Typical Workflow

# 1. Start services
task dev:up

# 2. Run backend (live reload)
task dev:air

# 3. Run frontend (hot reload)
cd frontend && flutter run -d chrome

# 4. Make changes → auto reload

# 5. Run tests
task test

# 6. Commit changes
git add .
git commit -m "feat: add new feature"

# 7. Push
git push origin feature-branch

Available Tasks

# Lihat semua available tasks
task --list

# Development
task dev:up          # Start all services
task dev:down        # Stop all services
task dev:air         # Run backend with live reload
task dev:logs        # View logs

# Database
task db:migrate:up   # Run migrations
task db:migrate:down # Rollback migrations
task db:seed         # Seed data
task db:reset        # Reset database

# Testing
task test            # Run all tests
task test:backend    # Run backend tests
task test:frontend   # Run frontend tests
task test:coverage   # Generate coverage report

# Linting
task lint            # Run linters
task lint:fix        # Auto-fix lint issues

# Build
task build           # Build all
task build:backend   # Build backend binary
task build:frontend  # Build Flutter app

🚨 Troubleshooting

Port already in use

Problem: Port 8080 atau 3306 sudah digunakanSolution:

# Check port usage
lsof -i :8080
lsof -i :3306

# Kill process
kill -9 <PID>

# Atau ubah port di .env
APP_PORT=8081
MYSQL_PORT=3307

Docker containers tidak start

Problem: docker compose up gagalSolution:

# Check Docker status
docker info

# Remove old containers
docker compose down -v

# Rebuild images
docker compose up -d --build

# Check logs
docker compose logs -f

Go modules error

Problem: go mod download gagalSolution:

# Clean cache
go clean -modcache

# Re-download
go mod download

# Tidy modules
go mod tidy

Flutter pub get error

Problem: flutter pub get gagalSolution:

# Clean Flutter
flutter clean

# Get packages
flutter pub get

# Upgrade packages
flutter pub upgrade

Database connection error

Problem: Backend tidak bisa connect ke MySQL/MongoDBSolution:

# Check containers running
docker compose ps

# Check database logs
docker compose logs mysql
docker compose logs mongodb

# Verify credentials di .env
# Restart backend

📚 Next Steps

Project Structure

Pahami struktur folder dan file

Architecture Overview

Lihat arsitektur sistem

Backend Development

Mulai develop backend service

Frontend Development

Mulai develop Flutter app

Pro Tip: Gunakan tmux atau split terminal untuk menjalankan backend dan frontend secara bersamaan!

Introduction

Documentation Index

​Local Setup

​🚀 Quick Start

​📁 1. Clone Repository

​⚙️ 2. Environment Configuration

​Copy Environment File

​Edit .env

​🐳 3. Start Development Services

​Menggunakan Taskfile

​Manual dengan Docker Compose

​Services yang Berjalan

​🔧 4. Backend Setup (Go)

​Install Dependencies

​Database Migration

​Run Backend

​Verify Backend

​📱 5. Frontend Setup (Flutter)

​Install Dependencies

​Environment Configuration

​Run Flutter App

​Verify Frontend

​🧪 6. Verify Setup

​Run Tests

​Check Services Health

​📊 7. Access Observability

​Grafana Dashboards

​Loki (Logs)

​Tempo (Traces)

​🔄 8. Development Workflow

​Typical Workflow

​Available Tasks

​🚨 Troubleshooting

​📚 Next Steps

Project Structure

Architecture Overview

Backend Development

Frontend Development

Local Setup

🚀 Quick Start

📁 1. Clone Repository

⚙️ 2. Environment Configuration

Copy Environment File

Edit `.env`

🐳 3. Start Development Services

Menggunakan Taskfile

Manual dengan Docker Compose

Services yang Berjalan

🔧 4. Backend Setup (Go)

Install Dependencies

Database Migration

Run Backend

Verify Backend

📱 5. Frontend Setup (Flutter)

Install Dependencies

Environment Configuration

Run Flutter App

Verify Frontend

🧪 6. Verify Setup

Run Tests

Check Services Health

📊 7. Access Observability

Grafana Dashboards

Loki (Logs)

Tempo (Traces)

🔄 8. Development Workflow

Typical Workflow

Available Tasks

🚨 Troubleshooting

📚 Next Steps