Quick Start Guide

Get the IBW Backend Service up and running in minutes.

Prerequisites

Go 1.23.1+
PostgreSQL 12+
Redis 6+
Docker (optional, for easy setup)

Step 1: Clone and Install

# Clone the repository
git clone <repository-url>
cd ibw-app-service
 
# Install dependencies
go mod download

Step 2: Setup Database and Redis

Option A: Using Docker Compose (Recommended)

# Start PostgreSQL and Redis
docker compose up -d postgres redis
 
# Wait a few seconds for services to start
sleep 5

Option B: Manual Setup

# Start PostgreSQL (adjust for your system)
brew services start postgresql  # macOS
# or
sudo systemctl start postgresql  # Linux
 
# Start Redis
brew services start redis  # macOS
# or
sudo systemctl start redis  # Linux
 
# Create database
createdb ibw

Step 3: Configure Environment

Create a .env file:

cp .env.example .env  # If example exists
# Or create manually

Minimum .env configuration:

APP_ENV=development
HTTP_PORT=8080

# Database
DB_HOST=localhost
DB_PORT=5432
DB_USER=postgres
DB_PASSWORD=postgres
DB_NAME=ibw
DB_SSLMODE=disable

# Redis
REDIS_HOST=localhost
REDIS_PORT=6379
REDIS_PASSWORD=
REDIS_DATABASE=0

# Telegram (optional for basic testing)
TELEGRAM_BOT_TOKEN=your_token_here

# Admin API (optional for basic testing)
ADMIN_API_KEY=your_admin_key_here

Step 4: Run Migrations

# Set database URL
export DATABASE_URL=postgres://postgres:postgres@localhost:5432/ibw?sslmode=disable
 
# Run migrations
make migrate-up
 
# Or using migrate directly
migrate -path migrations -database "$DATABASE_URL" up

Step 5: Start the Server

# Development mode
make run
 
# Or directly
go run cmd/server/main.go

You should see:

Server listening on :8080

Step 6: Verify Installation

Test the health endpoint:

curl http://localhost:8080/healthz

Expected response:

{
  "status": "ok"
}

Next Steps

Test Public Endpoints

# List events
curl http://localhost:8080/api/v1/events
 
# List conferences
curl http://localhost:8080/api/v1/conferences
 
# List speakers
curl http://localhost:8080/api/v1/speakers

Test Admin Endpoints

# List users (requires admin API key)
curl http://localhost:8080/api/v1/admin/users \
  -H "X-API-Key: your_admin_key_here"

Test User Endpoints

# Get user profile (requires Telegram auth)
curl http://localhost:8080/api/v1/users/me \
  -H "X-Telegram-Auth: your_telegram_auth_data"

Common Issues

Database Connection Error

Error: failed to connect to postgres

Solution:

Verify PostgreSQL is running: psql -U postgres -h localhost
Check database exists: psql -U postgres -l | grep ibw
Verify connection string in .env

Redis Connection Error

Error: failed to connect to redis

Solution:

Verify Redis is running: redis-cli ping
Check Redis configuration in .env
Test connection: redis-cli -h localhost -p 6379

Migration Errors

Error: Migration fails

Solution:

Check database connection
Verify migrations directory exists
Check for migration conflicts
Review migration logs

Port Already in Use

Error: bind: address already in use

Solution:

Change HTTP_PORT in .env
Or stop the process using port 8080:
```
lsof -ti:8080 | xargs kill
```

Development Tips

Hot Reload (Optional)

Install air for hot reloading:

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

View Logs

Logs are output to console. For file logging, configure logger in code.

Database Management

# Connect to database
psql -U postgres -d ibw
 
# View tables
\dt
 
# View migrations
SELECT * FROM schema_migrations;

Redis Management

# Connect to Redis
redis-cli
 
# View keys
KEYS *
 
# Clear cache (careful!)
FLUSHDB

Production Deployment

For production deployment:

Set APP_ENV=production
Use strong passwords
Enable SSL for database
Configure proper CORS
Set up monitoring
Configure backups
Use environment-specific configs

See Setup & Configuration for details.

Getting Help

Check Architecture for system overview
See API Endpoints for API reference
Review Services for business logic
Check Models for data structures

What's Next?

Explore the API Documentation
Learn about Authentication
Understand Middleware
Review Services

Middleware Database Migrations