single_binary

README

Single Binary Deployment Example

This example demonstrates how to build and deploy a production-ready Beluga AI application as a single binary with proper health checks, configuration management, graceful shutdown, and OTEL instrumentation.

Prerequisites

• Go 1.24+: Required for the Beluga AI framework
• OTEL Collector (optional): For exporting traces and metrics
• Docker (optional): For containerized deployment

What You'll Learn

• Building a single binary with embedded assets
• Implementing health check endpoints
• Loading configuration from multiple sources
• Graceful shutdown with request draining
• OTEL setup for production observability

Files

File	Description
main.go	Production-ready deployment example
main_test.go	Test suite for deployment features
deployment_guide.md	Comprehensive deployment guide

Usage

Build the Binary

go build -o beluga-server ./main.go

Run with Configuration

# Using environment variables
export BELUGA_PORT=8080
export OPENAI_API_KEY=sk-...
./beluga-server

# Using config file
./beluga-server --config config.yaml

Health Checks

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

# Readiness check
curl http://localhost:8080/readyz

Graceful Shutdown

The server handles SIGTERM and SIGINT signals, draining requests before shutdown:

# Send shutdown signal
kill -TERM $(pidof beluga-server)

Testing

go test -v ./...

Configuration Options

Option	Environment Variable	Default	Description
Port	BELUGA_PORT	8080	HTTP server port
Shutdown Timeout	BELUGA_SHUTDOWN_TIMEOUT	30s	Graceful shutdown timeout
OTEL Endpoint	OTEL_EXPORTER_OTLP_ENDPOINT	localhost:4317	OTEL collector endpoint

Related Examples

• Monitoring Example: Basic OTEL setup
• Config Formats Example: Configuration patterns

Related Documentation

• Observability Tracing Guide: Distributed tracing setup
• Monitoring Dashboards Use Case: Prometheus and Grafana setup

Documentation

Overview

Package main provides a production-ready single binary deployment example for Beluga AI applications. This example demonstrates: - Proper application lifecycle management - Health check endpoints (liveness, readiness, startup) - Graceful shutdown with request draining - OpenTelemetry integration for observability - Configuration via environment variables - Prometheus metrics exposure

Build and run:

go build -o ai-service ./main.go
OPENAI_API_KEY=sk-... ./ai-service