Quickstart

Get FlexPrice running locally and ingest your first usage event

Prerequisites

Before you begin, ensure you have the following installed:

Docker

Install Docker for running containerized services

Docker Compose

Install Docker Compose for multi-container orchestration

FlexPrice supports Linux, macOS (Darwin), and WSL under Windows.

Setup FlexPrice

1. Clone the Repository

   Clone the FlexPrice repository from GitHub:

   git clone https://github.com/flexprice/flexprice
   cd flexprice
   
2. Start All Services

   Run the complete development environment setup with a single command:

   make dev-setup
   

   This command will:

   • Start all required infrastructure (PostgreSQL, Kafka, ClickHouse, Temporal)
   • Build the FlexPrice application image
   • Run database migrations and initialize Kafka
   • Start all FlexPrice services (API, Consumer, Worker)

   The setup process may take a few minutes on first run as it downloads Docker images and builds the application.

3. Verify Services are Running

   Once setup is complete, verify all services are running:

   docker compose ps
   

   You should see the following services running:

   • postgres - PostgreSQL database
   • kafka - Apache Kafka message broker
   • clickhouse - ClickHouse analytics database
   • temporal - Temporal workflow engine
   • temporal-ui - Temporal web interface
   • flexprice-api - FlexPrice API server
   • flexprice-consumer - Event consumer service
   • flexprice-worker - Temporal worker service
4. Access the Services

   Once running, you can access the following services:

   FlexPrice API

   http://localhost:8080

   Main API endpoint for ingesting events and managing billing

   Temporal UI

   http://localhost:8088

   Monitor workflow executions and debug workflows

   Kafka UI

   http://localhost:8084

   View Kafka topics and messages (requires --profile dev)

   ClickHouse

   http://localhost:8123

   Query analytics and event data

   To access Kafka UI, restart with the dev profile:

   docker compose --profile dev up -d kafka-ui
   

Ingest Your First Event

Now that FlexPrice is running, let’s send your first usage event to track customer activity.

1. Get Your API Key

   For local development, use the default API key:

   export API_KEY="0cc505d7b917e0b1f25ccbea029dd43f4002edfea46b7f941f281911246768fe"
   

   This is a development API key. In production, you’ll generate unique API keys per environment.

2. Send a Usage Event

   Send a test usage event using curl:

   curl

   curl -X POST http://localhost:8080/v1/events \
     -H "Content-Type: application/json" \
     -H "X-API-Key: 0cc505d7b917e0b1f25ccbea029dd43f4002edfea46b7f941f281911246768fe" \
     -d '{
       "customer_id": "customer_123",
       "event_name": "api_call",
       "timestamp": "'$(date -u +"%Y-%m-%dT%H:%M:%SZ")'",
       "properties": {
         "endpoint": "/api/v1/users",
         "method": "GET",
         "response_time_ms": 145
       }
     }'
   
3. Verify Event Ingestion

   Check that your event was processed successfully:

   View in Kafka UI:

   1. Navigate to http://localhost:8084
   2. Click on the events topic
   3. View the latest messages

   Query in ClickHouse:

   docker compose exec clickhouse clickhouse-client \
     --user=flexprice \
     --password=flexprice123 \
     --database=flexprice \
     --query="SELECT * FROM events ORDER BY timestamp DESC LIMIT 5"
   

   Check API Logs:

   docker compose logs -f flexprice-api
   

Using the SDKs

For production applications, use one of our official SDKs:

Go

go get github.com/flexprice/go-sdk

SDK documentation and examples are available in the API Reference section.

Useful Commands

Here are some helpful commands for managing your local FlexPrice installation:

Restart Services

# Restart only FlexPrice services (not infrastructure)
make restart-flexprice

Next Steps

Architecture Overview

Learn about FlexPrice’s system architecture and technology stack

Create Pricing Plans

Set up pricing plans for your customers

Configure Meters

Define what usage metrics to track

API Reference

Explore all available API endpoints

Troubleshooting

Services fail to start

Ensure Docker has enough resources allocated (at least 4GB RAM recommended).

Check Docker daemon status:

docker info

View detailed logs:

docker compose logs

Database connection errors

Check database service health:

docker compose ps postgres clickhouse

View database logs:

docker compose logs postgres
docker compose logs clickhouse

Verify database is accepting connections:

docker compose exec postgres pg_isready -U flexprice

Kafka connection issues

Verify Kafka is running:

docker compose logs kafka

List Kafka topics:

docker compose exec kafka kafka-topics --bootstrap-server kafka:9092 --list

Reinitialize Kafka topics:

make init-kafka

Events not appearing in ClickHouse

Check consumer service logs:

docker compose logs -f flexprice-consumer

Verify Kafka consumer group status:

docker compose exec kafka kafka-consumer-groups \
  --bootstrap-server kafka:9092 \
  --describe \
  --group flexprice-consumer-group

Check ClickHouse for recent events:

docker compose exec clickhouse clickhouse-client \
  --user=flexprice \
  --password=flexprice123 \
  --query="SELECT count() FROM flexprice.events"

For more help, join our Slack community or open an issue on GitHub.