Setup & Configuration

Prerequisites

Go 1.23.1 or higher
PostgreSQL 12+
Redis 6+
Docker and Docker Compose (optional)

Environment Setup

1. Clone Repository

git clone <repository-url>
cd ibw-app-service

2. Install Dependencies

go mod download

3. Environment Variables

Create a .env file in the root directory:

# Application
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
# Or use DATABASE_URL
DATABASE_URL=postgres://postgres:postgres@localhost:5432/ibw?sslmode=disable

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

# Telegram
TELEGRAM_BOT_TOKEN=your_bot_token
TELEGRAM_BOT_STAGING_TOKEN=your_staging_token
TELEGRAM_GROUP_CHAT_ID=your_group_chat_id

# External APIs
APIFY_API_TOKEN=your_apify_token
SOCIAL_API_TOKEN=your_social_api_token
MAX_TWEETS_TO_FETCH=100
MAX_TWEETS_TO_STORE=100

# Azure OpenAI
AZURE_OPENAI_ENDPOINT=your_endpoint
AZURE_OPENAI_KEY=your_key
AZURE_OPENAI_VERSION=2023-05-15
AZURE_OPENAI_MODEL_NAME=gpt-4

# Azure Storage
AZURE_STORAGE_CONNECTION_STRING=your_connection_string
AZURE_STORAGE_CONTAINER_NAME=your_container

# Cloudflare R2
CLOUDFLARE_R2_ENDPOINT=your_endpoint
CLOUDFLARE_R2_ACCESS_KEY_ID=your_access_key
CLOUDFLARE_R2_SECRET_ACCESS_KEY=your_secret_key
CLOUDFLARE_R2_BUCKET_NAME=your_bucket
CLOUDFLARE_R2_PUBLIC_URL=your_public_url
CLOUDFLARE_R2_USE_R2_DEV=true

# Admin API
ADMIN_API_KEY=your_admin_api_key

# Telegram Notification Service
TELEGRAM_NOTIFICATION_SERVICE_URL=https://your-service-url
TELEGRAM_NOTIFICATION_API_KEY=your_api_key

# Testing/Dry Run
DRY_RUN=false
DRY_RUN_TELEGRAM_ID=0

Database Setup

Using Docker Compose

docker compose up -d postgres redis

Manual Setup

Create PostgreSQL database:

createdb ibw

Run migrations:

export DATABASE_URL=postgres://postgres:postgres@localhost:5432/ibw?sslmode=disable
make migrate-up

Or using the migration tool directly:

migrate -path migrations -database "$DATABASE_URL" up

Running the Application

Development Mode

make run

Or directly:

go run cmd/server/main.go

Production Mode

Build the binary:

make build

Run the binary:

./bin/ibw-backend

Using Docker

docker compose up -d --build

Configuration Details

Application Configuration

APP_ENV: Environment (development, staging, production)
HTTP_PORT: HTTP server port (default: 8080)

Database Configuration

The application supports two ways to configure database:

Individual fields:
- DB_HOST, DB_PORT, DB_USER, DB_PASSWORD, DB_NAME, DB_SSLMODE
Connection string:
- DATABASE_URL: Full PostgreSQL connection string

If DATABASE_URL is provided, it takes precedence.

Redis Configuration

REDIS_HOST: Redis host (default: localhost)
REDIS_PORT: Redis port (default: 6379)
REDIS_PASSWORD: Redis password (optional)
REDIS_DATABASE: Redis database number (default: 0)

Telegram Configuration

TELEGRAM_BOT_TOKEN: Production bot token
TELEGRAM_BOT_STAGING_TOKEN: Staging bot token
TELEGRAM_GROUP_CHAT_ID: Group chat ID for notifications

External API Configuration

Apify (Twitter)

APIFY_API_TOKEN: Apify API token for Twitter data

Social API

SOCIAL_API_TOKEN: Social API token
MAX_TWEETS_TO_FETCH: Maximum tweets to fetch (default: 100)
MAX_TWEETS_TO_STORE: Maximum tweets to store (default: 100)

Azure Configuration

Azure OpenAI

AZURE_OPENAI_ENDPOINT: Azure OpenAI endpoint
AZURE_OPENAI_KEY: Azure OpenAI API key
AZURE_OPENAI_VERSION: API version (default: 2023-05-15)
AZURE_OPENAI_MODEL_NAME: Model name (default: gpt-4)

Azure Storage

AZURE_STORAGE_CONNECTION_STRING: Azure Storage connection string
AZURE_STORAGE_CONTAINER_NAME: Container name

Cloudflare Configuration

Cloudflare R2

CLOUDFLARE_R2_ENDPOINT: R2 endpoint URL
CLOUDFLARE_R2_ACCESS_KEY_ID: R2 access key ID
CLOUDFLARE_R2_SECRET_ACCESS_KEY: R2 secret access key
CLOUDFLARE_R2_BUCKET_NAME: R2 bucket name
CLOUDFLARE_R2_PUBLIC_URL: Custom public URL (optional)
CLOUDFLARE_R2_USE_R2_DEV: Use r2.dev subdomain (default: true)

Admin API

ADMIN_API_KEY: API key for admin endpoints

Notification Service

TELEGRAM_NOTIFICATION_SERVICE_URL: Notification service URL
TELEGRAM_NOTIFICATION_API_KEY: Notification service API key

Testing Configuration

DRY_RUN: Enable dry run mode (default: false)
DRY_RUN_TELEGRAM_ID: Override all Telegram sends to this ID

Health Check

Once the server is running, verify it's working:

curl http://localhost:8080/healthz

Expected response:

{
  "status": "ok"
}

Common Issues

Database Connection Issues

Verify PostgreSQL is running:

psql -U postgres -h localhost

Check connection string format
Verify database exists
Check firewall/network settings

Redis Connection Issues

Verify Redis is running:

redis-cli ping

Check Redis configuration
Verify network access

Migration Issues

Check database connection
Verify migration files exist
Check for migration conflicts
Review migration logs

Production Deployment

Environment Variables

Set all required environment variables in your production environment.

Database Migrations

Always run migrations before deploying:

make migrate-up

Health Monitoring

Monitor the /healthz endpoint for health checks.

Logging

Configure logging level via APP_ENV:

development: Debug logging
production: Info and above

Security Considerations

Never commit .env files to version control
Use strong passwords for database and Redis
Rotate API keys regularly
Use HTTPS in production
Set proper CORS policies
Enable rate limiting for public endpoints
Use environment-specific configuration

Docker Compose

The docker-compose.yml file includes:

PostgreSQL service
Redis service
Application service (optional)

To start services:

docker compose up -d

To stop services:

docker compose down

Makefile Commands

Common Makefile commands:

make run - Run the application
make build - Build the binary
make migrate-up - Run database migrations
make migrate-down - Rollback migrations
make test - Run tests

Data Models Authentication