Deployment

FlexPrice supports multiple deployment modes, allowing you to scale components independently based on your needs.

Deployment Modes

FlexPrice can run in four different modes:

Mode	Description	Use Case
`local`	All services in one process	Development, testing
`api`	API server only	Horizontally scalable API tier
`consumer`	Kafka consumer only	Event processing tier
`temporal_worker`	Temporal worker only	Workflow execution tier

Set the mode via environment variable:

FLEXPRICE_DEPLOYMENT_MODE=api

Architecture Overview

┌─────────────────┐
│   Load Balancer │
└────────┬────────┘
         │
    ┌────┴────┐
    │         │
┌───▼──┐  ┌──▼───┐
│ API  │  │ API  │  ← FLEXPRICE_DEPLOYMENT_MODE=api
└───┬──┘  └──┬───┘
    │         │
    └────┬────┘
         │
    ┌────▼────────┐
    │    Kafka    │
    └────┬────────┘
         │
    ┌────┴─────┐
    │          │
┌───▼────┐ ┌──▼───────┐
│Consumer│ │ Consumer │  ← FLEXPRICE_DEPLOYMENT_MODE=consumer
└───┬────┘ └──┬───────┘
    │          │
    └─────┬────┘
          │
     ┌────▼──────┐
     │  Temporal │
     └────┬──────┘
          │
     ┌────┴──────┐
     │          │
 ┌───▼────┐ ┌──▼────┐
 │ Worker │ │Worker │  ← FLEXPRICE_DEPLOYMENT_MODE=temporal_worker
 └────────┘ └───────┘

Local Mode

Runs all components in a single process - ideal for development and testing.

FLEXPRICE_DEPLOYMENT_MODE=local

What Runs

API server (HTTP endpoints)
Kafka consumer (event processing)
Temporal worker (workflow execution)

Docker Compose Example

docker-compose.yml

services:
  flexprice:
    image: flexprice-app:latest
    environment:
      - FLEXPRICE_DEPLOYMENT_MODE=local
      - FLEXPRICE_POSTGRES_HOST=postgres
      - FLEXPRICE_KAFKA_BROKERS=kafka:9092
      - FLEXPRICE_CLICKHOUSE_ADDRESS=clickhouse:9000
      - FLEXPRICE_TEMPORAL_ADDRESS=temporal:7233
    ports:
      - "8080:8080"

Use Cases

Local development
Integration testing
Small deployments (less than 1000 events/day)

Local mode does not scale horizontally. Use separate modes for production workloads.

API Mode

Runs only the HTTP API server - no event processing or workflows.

FLEXPRICE_DEPLOYMENT_MODE=api

What Runs

API server (HTTP endpoints)
HTTP request handling
Database queries
Event publishing to Kafka

Docker Compose Example

docker-compose.yml

services:
  flexprice-api:
    image: flexprice-app:latest
    environment:
      - FLEXPRICE_DEPLOYMENT_MODE=api
      - FLEXPRICE_POSTGRES_HOST=postgres
      - FLEXPRICE_KAFKA_BROKERS=kafka:9092
      - FLEXPRICE_CLICKHOUSE_ADDRESS=clickhouse:9000
    ports:
      - "8080:8080"
    deploy:
      replicas: 3  # Scale horizontally
    restart: unless-stopped

Scaling Strategy

Add a load balancer

Use Nginx, HAProxy, or a cloud load balancer to distribute traffic:

nginx.conf

upstream flexprice_api {
    server flexprice-api-1:8080;
    server flexprice-api-2:8080;
    server flexprice-api-3:8080;
}

server {
    listen 80;
    location / {
        proxy_pass http://flexprice_api;
    }
}

Scale horizontally

Add more API replicas based on traffic:

docker compose up -d --scale flexprice-api=5

Monitor resource usage

Track CPU, memory, and request latency to determine when to scale.

Use Cases

High-traffic API endpoints
Stateless horizontal scaling
Separation of API and background processing

Consumer Mode

Runs only the Kafka consumer - processes events from Kafka topics.

FLEXPRICE_DEPLOYMENT_MODE=consumer

What Runs

Kafka consumer groups
Event processing pipelines:
- event_processing - Main event ingestion
- event_processing_lazy - Deferred processing
- feature_usage_tracking - Feature usage metering
- costsheet_usage_tracking - Cost calculation
- event_post_processing - Post-processing pipeline

Docker Compose Example

docker-compose.yml

services:
  flexprice-consumer:
    image: flexprice-app:latest
    environment:
      - FLEXPRICE_DEPLOYMENT_MODE=consumer
      - FLEXPRICE_POSTGRES_HOST=postgres
      - FLEXPRICE_KAFKA_BROKERS=kafka:9092
      - FLEXPRICE_CLICKHOUSE_ADDRESS=clickhouse:9000
      - FLEXPRICE_TEMPORAL_ADDRESS=temporal:7233
      # Configure which consumers to enable
      - FLEXPRICE_EVENT_PROCESSING_ENABLED=true
      - FLEXPRICE_FEATURE_USAGE_TRACKING_ENABLED=true
    deploy:
      replicas: 2
    restart: unless-stopped

Consumer Groups

FlexPrice uses multiple consumer groups for different processing stages:

Consumer Group	Topic	Purpose
`v1_event_processing`	`events`	Primary event processing
`v1_event_processing_lazy`	`events_lazy`	Deferred processing
`v1_feature_tracking_service`	`events`	Feature usage tracking
`v1_costsheet_usage_tracking_service`	`events`	Usage cost calculation
`v1_events_post_processing`	`events_post_processing`	Post-processing

Scaling Strategy

Increase Kafka partitions

More partitions allow more parallel consumers:

docker compose exec kafka kafka-topics --bootstrap-server kafka:9092 \
  --alter --topic events --partitions 10

Scale consumer replicas

Add consumers up to the number of partitions:

docker compose up -d --scale flexprice-consumer=10

Adjust rate limits

Configure processing rate limits in config.yaml or via environment:

FLEXPRICE_EVENT_PROCESSING_RATE_LIMIT=100
FLEXPRICE_FEATURE_USAGE_TRACKING_RATE_LIMIT=50

Use Cases

High event throughput (>10,000 events/second)
Backfill operations
Dedicated event processing tier

Temporal Worker Mode

Runs only Temporal workflow workers - executes long-running workflows.

FLEXPRICE_DEPLOYMENT_MODE=temporal_worker

What Runs

Temporal workflow workers
Billing workflows
Invoice generation workflows
Subscription lifecycle workflows

Docker Compose Example

docker-compose.yml

services:
  flexprice-worker:
    image: flexprice-app:latest
    environment:
      - FLEXPRICE_DEPLOYMENT_MODE=temporal_worker
      - FLEXPRICE_POSTGRES_HOST=postgres
      - FLEXPRICE_TEMPORAL_ADDRESS=temporal:7233
      - FLEXPRICE_TEMPORAL_TASK_QUEUE=billing-task-queue
    deploy:
      replicas: 3
    restart: unless-stopped

Scaling Strategy

Determine workflow concurrency

Monitor active workflows in Temporal UI:

http://localhost:8088

Scale workers based on queue depth

Add workers if queue depth is consistently high:

docker compose up -d --scale flexprice-worker=5

Configure task queue routing

Use multiple task queues for different workflow types:

FLEXPRICE_TEMPORAL_TASK_QUEUE=billing-high-priority

Use Cases

Long-running billing workflows
High workflow concurrency
Dedicated workflow processing tier

Production Deployment Example

Complete production setup with all three modes:

docker-compose.yml

services:
  # API Tier (3 replicas for high availability)
  flexprice-api:
    image: flexprice-app:latest
    environment:
      - FLEXPRICE_DEPLOYMENT_MODE=api
      - FLEXPRICE_POSTGRES_HOST=postgres
      - FLEXPRICE_KAFKA_BROKERS=kafka-1:9092,kafka-2:9092,kafka-3:9092
      - FLEXPRICE_CLICKHOUSE_ADDRESS=clickhouse:9000
      - FLEXPRICE_TEMPORAL_ADDRESS=temporal:7233
      - FLEXPRICE_LOGGING_LEVEL=info
    ports:
      - "8080:8080"
    deploy:
      replicas: 3
      resources:
        limits:
          cpus: '2'
          memory: 2G
    restart: unless-stopped

  # Consumer Tier (2 replicas for event processing)
  flexprice-consumer:
    image: flexprice-app:latest
    environment:
      - FLEXPRICE_DEPLOYMENT_MODE=consumer
      - FLEXPRICE_POSTGRES_HOST=postgres
      - FLEXPRICE_KAFKA_BROKERS=kafka-1:9092,kafka-2:9092,kafka-3:9092
      - FLEXPRICE_CLICKHOUSE_ADDRESS=clickhouse:9000
      - FLEXPRICE_TEMPORAL_ADDRESS=temporal:7233
      - FLEXPRICE_EVENT_PROCESSING_RATE_LIMIT=100
    deploy:
      replicas: 2
      resources:
        limits:
          cpus: '2'
          memory: 2G
    restart: unless-stopped

  # Worker Tier (2 replicas for workflows)
  flexprice-worker:
    image: flexprice-app:latest
    environment:
      - FLEXPRICE_DEPLOYMENT_MODE=temporal_worker
      - FLEXPRICE_POSTGRES_HOST=postgres
      - FLEXPRICE_TEMPORAL_ADDRESS=temporal:7233
      - FLEXPRICE_TEMPORAL_TASK_QUEUE=billing-task-queue
    deploy:
      replicas: 2
      resources:
        limits:
          cpus: '1'
          memory: 1G
    restart: unless-stopped

Kubernetes Deployment

For Kubernetes deployments, create separate Deployments for each mode:

k8s/api-deployment.yaml

apiVersion: apps/v1
kind: Deployment
metadata:
  name: flexprice-api
spec:
  replicas: 3
  selector:
    matchLabels:
      app: flexprice
      component: api
  template:
    metadata:
      labels:
        app: flexprice
        component: api
    spec:
      containers:
      - name: flexprice
        image: flexprice-app:latest
        env:
        - name: FLEXPRICE_DEPLOYMENT_MODE
          value: "api"
        - name: FLEXPRICE_POSTGRES_HOST
          valueFrom:
            secretKeyRef:
              name: flexprice-secrets
              key: postgres-host
        ports:
        - containerPort: 8080
        resources:
          requests:
            cpu: 500m
            memory: 512Mi
          limits:
            cpu: 2000m
            memory: 2Gi

See the Scaling Guide for advanced Kubernetes configurations including HPA and resource tuning.

Health Checks

Each deployment mode exposes health check endpoints:

# API mode
curl http://localhost:8080/health

# Consumer mode - check via logs
docker compose logs flexprice-consumer

# Worker mode - check Temporal UI
open http://localhost:8088

Migration Strategy

Moving from local to split deployment:

Start with local mode

Deploy initially in local mode to validate the setup.

Separate the API tier

Move to API mode for the public-facing service:

FLEXPRICE_DEPLOYMENT_MODE=api

Add consumer tier

Deploy consumer instances for event processing:

FLEXPRICE_DEPLOYMENT_MODE=consumer

Add worker tier

Deploy Temporal workers for workflows:

FLEXPRICE_DEPLOYMENT_MODE=temporal_worker

Scale independently

Monitor and scale each tier based on load.

Get Started

Core Concepts

Usage Metering

Pricing & Plans

Credits & Wallets

Billing & Invoicing

Integrations

Self-Hosting

Deployment Modes

Architecture Overview

Local Mode

What Runs

Docker Compose Example

Use Cases

API Mode

What Runs

Docker Compose Example

Scaling Strategy

Use Cases

Consumer Mode

What Runs

Docker Compose Example

Consumer Groups

Scaling Strategy

Use Cases

Temporal Worker Mode

What Runs

Docker Compose Example

Scaling Strategy

Use Cases

Production Deployment Example

Kubernetes Deployment

Health Checks

Migration Strategy

Next Steps

Get Started

Core Concepts

Usage Metering

Pricing & Plans

Credits & Wallets

Billing & Invoicing

Integrations

Self-Hosting

​Deployment Modes

​Architecture Overview

​Local Mode

​What Runs

​Docker Compose Example

​Use Cases

​API Mode

​What Runs

​Docker Compose Example

​Scaling Strategy

​Use Cases

​Consumer Mode

​What Runs

​Docker Compose Example

​Consumer Groups

​Scaling Strategy

​Use Cases

​Temporal Worker Mode

​What Runs

​Docker Compose Example

​Scaling Strategy

​Use Cases

​Production Deployment Example

​Kubernetes Deployment

​Health Checks

​Migration Strategy

​Next Steps

Deployment Modes

Architecture Overview

Local Mode

What Runs

Docker Compose Example

Use Cases

API Mode

What Runs

Docker Compose Example

Scaling Strategy

Use Cases

Consumer Mode

What Runs

Docker Compose Example

Consumer Groups

Scaling Strategy

Use Cases

Temporal Worker Mode

What Runs

Docker Compose Example

Scaling Strategy

Use Cases

Production Deployment Example

Kubernetes Deployment

Health Checks

Migration Strategy

Next Steps