Setup Guide

Complete guide to setting up Mend for local development.

Prerequisites Installation

1. Install Go 1.21+

   macOS

   brew install go
   go version  # Verify installation

   Linux

   wget https://go.dev/dl/go1.21.0.linux-amd64.tar.gz
   sudo tar -C /usr/local -xzf go1.21.0.linux-amd64.tar.gz
   export PATH=$PATH:/usr/local/go/bin
   go version

   Windows

   Download and install from go.dev/dl

2. Install Redis

   macOS

   brew install redis
   brew services start redis
   redis-cli ping  # Should return PONG

   Linux

   sudo apt-get install redis-server
   sudo systemctl start redis
   redis-cli ping

   Docker

   docker run -d -p 6379:6379 --name redis redis:7-alpine

3. Install FFmpeg

   macOS

   brew install ffmpeg
   ffmpeg -version

   Linux

   sudo apt-get install ffmpeg
   ffmpeg -version

   Windows

   Download from ffmpeg.org

   Add to PATH environment variable

Project Setup

1. Clone and Initialize

   cd /path/to/your/projects
   git clone https://github.com/yourusername/mend.git
   cd mend
   
   # Download Go dependencies
   go mod download
   go mod tidy

2. Configure Application

   # Copy example configuration
   cp config.example.yaml config.yaml
   cp .env.example .env

3. Edit Configuration Files

   config.yaml

   config.yaml

   server:
     port: 8080
     mode: debug  # Use 'debug' for development
     api_keys:
       - "${API_KEY_1}"
   
   redis:
     addr: localhost:6379
     password: ""
     db: 0
   
   s3:
     region: us-east-1
     access_key_id: "${AWS_ACCESS_KEY_ID}"
     secret_access_key: "${AWS_SECRET_ACCESS_KEY}"
   
   worker:
     concurrency: 5  # Adjust based on CPU cores
   
   processing:
     temp_dir: /tmp/mend
     ffmpeg_path: ffmpeg

   .env

   .env

   # AWS Credentials
   AWS_ACCESS_KEY_ID=your_access_key
   AWS_SECRET_ACCESS_KEY=your_secret_key
   AWS_REGION=us-east-1
   
   # API Key
   API_KEY_1=$(openssl rand -hex 32)

   MinIO (Local)

   config.yaml

   s3:
     region: us-east-1
     endpoint: "http://localhost:9000"
     access_key_id: "minioadmin"
     secret_access_key: "minioadmin"
     use_path_style: true

4. Create Temp Directory

   mkdir -p /tmp/mend

Running Locally

Go Run

Terminal 1 - API Server:

go run cmd/api/main.go

Terminal 2 - Worker:

go run cmd/worker/main.go

Build & Run

# Build binaries
make build

# Run API (Terminal 1)
./bin/api

# Run Worker (Terminal 2)
./bin/worker

Docker Compose

# Start all services
docker-compose up -d

# View logs
docker-compose logs -f

# Stop services
docker-compose down

Tip

Docker Compose includes Redis, MinIO, API, and Workers - perfect for local development!

Testing the API

Health Check

curl http://localhost:8080/health

Expected Response

{
  "status": "healthy",
  "service": "mend-media-engine"
}

API Documentation

Open in your browser:

http://localhost:8080/swagger/index.html

Test with MinIO (Local S3)

1. Start MinIO

   docker-compose up -d minio

2. Access MinIO Console

   • URL: http://localhost:9001
   • Username: minioadmin
   • Password: minioadmin

3. Create a Bucket

   • Click “Buckets” → “Create Bucket”
   • Name: test-bucket

4. Upload Test Image

   • Navigate to bucket
   • Click “Upload” → Select an image file

5. Test Resize Endpoint

   curl -X POST http://localhost:8080/api/v1/jobs/image/resize \
     -H "Content-Type: application/json" \
     -H "X-API-Key: your_api_key_here" \
     -d '{
       "source_bucket": "test-bucket",
       "source_key": "test-image.jpg",
       "dest_bucket": "test-bucket",
       "dest_key": "resized-image.jpg",
       "width": 800,
       "height": 600
     }'

Development Workflow

Running Tests

# Run all tests
go test ./...

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

# Run specific package
go test ./internal/processor/image

# Generate coverage report
go test -coverprofile=coverage.out ./...
go tool cover -html=coverage.out

Code Formatting

# Format code
go fmt ./...

# Run linter
golangci-lint run

# Install linter if needed
brew install golangci-lint

Generate API Documentation

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

# Generate docs
swag init -g cmd/api/main.go -o docs

# Docs available at /swagger/index.html

Hot Reload (Optional)

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

# Run with hot reload
air

Project Structure

• Directorycmd/

  • Directoryapi/

    • main.go
  • Directoryworker/

    • main.go
• Directoryinternal/

  • Directoryapi/

    • Directoryhandlers/

      • …
    • Directorymiddleware/

      • …
    • Directoryroutes/

      • …
  • Directoryprocessor/

    • Directoryimage/

      • …
    • Directoryvideo/

      • …
    • Directoryaudio/

      • …
  • Directoryqueue/

    • …
  • Directorystorage/

    • …
• config.yaml
• .env
• docker-compose.yaml
• Makefile

Troubleshooting

”command not found: go"

brew install go
# or download from go.dev

"connection refused” to Redis

Start Redis

brew services start redis

Docker

docker run -d -p 6379:6379 redis:7-alpine

Check Status

redis-cli ping
# Should return: PONG

FFmpeg not found

# Install FFmpeg
brew install ffmpeg

# Or specify full path in config.yaml
processing:
  ffmpeg_path: /usr/local/bin/ffmpeg

S3 access denied

# Verify credentials are set
echo $AWS_ACCESS_KEY_ID
echo $AWS_SECRET_ACCESS_KEY

# Test with AWS CLI
aws s3 ls

Worker not processing jobs

1. Check Redis is running:

   redis-cli ping

2. Check worker logs for errors

3. Verify queue configuration in config.yaml

4. Check Redis queue length:

   redis-cli LLEN asynq:queues:image

Port already in use

config.yaml

server:
  port: 8081  # Use different port

Useful Commands

Build

make build

Test

make test

Clean

make clean

Docker Up

make docker-up

IDE Setup

VS Code

Recommended Extensions:

• Go (golang.go)
• Docker (ms-azuretools.vscode-docker)
• YAML (redhat.vscode-yaml)
• REST Client (humao.rest-client)

GoLand

Project should work out of the box:

1. Set GOROOT to your Go installation
2. Enable Go Modules
3. Set working directory to project root

Next Steps

Read API Docs

Explore the API Reference

Try Examples

Check the examples/ directory for sample code

Deploy

See the Deployment Guide

Architecture

Understand the Architecture