Base Stack Admin API Template

Go backend API template using Base Framework for building admin applications with CRUD operations, authentication, file storage, and more.

Prerequisites

Before starting, ensure you have the following installed:

Required Dependencies

macOS

# Install Go (1.21 or higher)
brew install go

# Install image processing libraries (required for media handling)
brew install webp libheif

# Install PostgreSQL (or use Docker)
brew install postgresql@15

Ubuntu/Debian Linux

# Install Go (1.21 or higher)
sudo apt update
sudo apt install golang-go

# Install image processing libraries (required for media handling)
sudo apt install libwebp-dev libheif-dev

# Install PostgreSQL
sudo apt install postgresql postgresql-contrib

Verify Installation

# Check Go version
go version  # Should be 1.21 or higher

# Check webp installation
pkg-config --modversion libwebp

# Check heif installation
pkg-config --modversion libheif

Why webp and heif?

• The Base Framework's media module uses these libraries for image processing
• libwebp - WebP image format support for optimized web images
• libheif - HEIF/HEIC image format support (iPhone photos)
• Without these libraries, the build will fail with linker errors

Quick Start

1. Environment Setup

# Copy environment template
cp .env.example .env

# Edit .env with your database credentials
nano .env

Key environment variables:

APP_PORT=8000
DB_HOST=localhost
DB_PORT=5432
DB_USER=postgres
DB_PASSWORD=your_password
DB_NAME=admin_db
JWT_SECRET=your-secret-key-change-in-production

2. Database Setup

# Create database
createdb admin_db

# Or using psql
psql -U postgres -c "CREATE DATABASE admin_db;"

3. Run Application

# Install Go dependencies
go mod tidy

# Run with Swagger docs generation (first time)
bui start --docs

# Or run directly with Go
go run main.go

The API will be available at:

• API: http://localhost:8000/api
• Swagger Docs: http://localhost:8000/swagger/

4. Build for Production

# Build binary
go build -o admin main.go

# Or use Bui CLI
bui build backend

# Run binary
./admin

Project Structure

admin-api-template/
├── app/                    # Your application modules
│   ├── models/            # GORM models (generated by Bui)
│   ├── [module]/          # Module directories (service, controller, validator)
│   └── init.go            # Module registration and authentication extension
├── core/                  # Base Framework core (DO NOT EDIT)
│   ├── app/              # Core modules (auth, profile, media, etc.)
│   ├── database/         # Database connection and migrations
│   ├── router/           # HTTP routing and middleware
│   ├── storage/          # File upload handling
│   ├── email/            # Email sending
│   ├── websocket/        # WebSocket support
│   ├── logger/           # Structured logging
│   └── ...
├── logs/                  # Application logs
│   └── app.log           # JSON structured logs
├── main.go               # Application entry point
├── .env                  # Environment configuration
└── go.mod

Module Development

Generate New Module

# Generate backend module with Bui CLI
bui generate backend product name:string price:float stock:int

# This creates:
# - app/products/model.go       # GORM model
# - app/products/service.go     # Business logic
# - app/products/controller.go  # HTTP handlers
# - app/products/module.go      # Route registration
# - app/products/validator.go   # Input validation

Register Module

After generating, manually register in app/init.go:

func GetAppModules() map[string]module.Module {
    modules := make(map[string]module.Module)

    // Register your modules here
    modules["products"] = products.Init(deps)

    return modules
}

Field Types Reference

Basic Types

• string - Text field
• text - Long text (textarea)
• int, uint - Integer numbers
• float - Decimal numbers
• bool - Boolean value
• time - Timestamp
• json - JSON data

Special Types

• translation - Translatable field (multi-language support)
• media:image - Image upload field
• media:file - File upload field

Relationships

• category:belongsTo:Category - Foreign key (many-to-one)
• tags:manyToMany:Tag - Many-to-many relationship

Example

bui g backend product \
  name:translation \
  sku:string \
  description:text \
  price:float \
  stock:int \
  category:belongsTo:Category \
  is_active:bool \
  thumbnail:media:image

Authentication Extension

Extend JWT claims in app/init.go:

func Extend(user_id uint) any {
    // Add custom claims to JWT token
    var user models.User
    db.First(&user, user_id)

    return map[string]any{
        "user_id": user_id,
        "role_id": user.RoleID,
        "company_id": user.CompanyID,
    }
}

Logging

The application uses structured logging with file and console output:

Log Files

• Location: logs/app.log
• Format: JSON (structured logging)
• Rotation: Automatic (configurable)

Verbose Mode

# Show detailed logs
go run main.go -v
# or
go run main.go --verbose

Log Levels

• INFO: General information (blue)
• WARN: Warning messages (yellow)
• ERROR: Error messages (red)
• DEBUG: Debug information (purple)
• FATAL: Fatal errors (bold red)

API Features

Core Endpoints (Auto-Available)

• Authentication: /api/auth/login, /api/auth/register
• Profile: /api/profile
• Media: /api/media/upload
• Settings: /api/settings
• Employees: /api/employees
• Search: /api/search

Generated Module Endpoints

For each generated module (e.g., products):

• GET /api/products - List with pagination/filters
• GET /api/products/all - Simplified list for dropdowns
• GET /api/products/:id - Get single item
• POST /api/products - Create new item
• PUT /api/products/:id - Update item
• DELETE /api/products/:id - Delete item

Storage Configuration

Local Storage (Default)

STORAGE_DRIVER=local
STORAGE_LOCAL_PATH=./storage
STORAGE_BASE_URL=http://localhost:8000/storage

S3 Storage

STORAGE_DRIVER=s3
STORAGE_S3_BUCKET=your-bucket
STORAGE_S3_REGION=us-east-1
STORAGE_S3_KEY=your-access-key
STORAGE_S3_SECRET=your-secret-key

Google Cloud Storage

STORAGE_DRIVER=gcs
STORAGE_GCS_BUCKET=your-bucket
STORAGE_GCS_PROJECT=your-project-id
STORAGE_GCS_CREDENTIALS=/path/to/credentials.json

Email Configuration

Postmark

EMAIL_DRIVER=postmark
EMAIL_FROM=noreply@yourdomain.com
EMAIL_FROM_NAME=Your App
POSTMARK_SERVER_TOKEN=your-token

SendGrid

EMAIL_DRIVER=sendgrid
EMAIL_FROM=noreply@yourdomain.com
EMAIL_FROM_NAME=Your App
SENDGRID_API_KEY=your-api-key

Development Tips

Hot Reload

Use air for hot reloading during development:

# Install air
go install github.com/cosmtrek/air@latest

# Run with hot reload
air

Database Migrations

Models are auto-migrated on startup. To disable:

AUTO_MIGRATE=false

Swagger Documentation

Generate Swagger docs before starting:

# Install swag
go install github.com/swaggo/swag/cmd/swag@latest

# Generate docs
swag init

# Or use Bui CLI
bui start --docs

Production Deployment

Build

# Build optimized binary
go build -ldflags="-s -w" -o admin main.go

Environment

APP_ENV=production
DEBUG=false
SWAGGER_ENABLED=false

Run

# Run with verbose logging
./admin -v

# Or use systemd/supervisor for process management

Troubleshooting

Build Errors with webp/heif

ld: library not found for -lwebp
ld: library not found for -lheif

Solution: Install image processing libraries (see Prerequisites section)

Database Connection Errors

failed to connect to database

Solution: Check database credentials in .env and ensure PostgreSQL is running

Port Already in Use

bind: address already in use

Solution: Change APP_PORT in .env or stop the process using port 8000

License

MIT