Installation

Install and set up FlexPrice for self-hosting

FlexPrice can be installed using Docker Compose for quick setup or directly from source for development.

Prerequisites

Before installing FlexPrice, ensure you have the following installed:

• Golang 1.23+
• Docker and Docker Compose
• Supported platforms:
  • Linux-based environment
  • macOS (Darwin)
  • WSL under Windows

Quick Setup with Docker Compose

The fastest way to get FlexPrice running is using the automated Docker Compose setup:

1. Clone the repository

   git clone https://github.com/flexprice/flexprice
   cd flexprice
   
2. Run the setup script

   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 topics
   • Start all FlexPrice services (API, Consumer, Worker)
3. Verify the installation

   Once setup is complete, verify the services are running:

   docker compose ps
   

   You should see all services in a healthy state.

Accessing Services

Once installation is complete, you can access:

• FlexPrice API: http://localhost:8080
• Temporal UI: http://localhost:8088
• Kafka UI: http://localhost:8084 (with profile ‘dev’)
• ClickHouse UI: http://localhost:8123

The API base URL for SDK configuration should include /v1: http://localhost:8080/v1

Manual Installation

For development or custom setups, you can install FlexPrice components individually.

Start Infrastructure Services

Start only the required infrastructure without the FlexPrice application:

docker compose up -d postgres kafka clickhouse temporal temporal-ui

Initialize Databases

1. Run PostgreSQL migrations

   make migrate-postgres
   
2. Run ClickHouse migrations

   make migrate-clickhouse
   
3. Generate and apply Ent migrations

   make generate-ent
   make migrate-ent
   

Initialize Kafka Topics

Create the required Kafka topics:

make init-kafka

Build and Run

Docker

# Build the FlexPrice image
make build-image

# Start FlexPrice services
make start-flexprice

Development Credentials

The default Docker Compose setup uses these credentials:

PostgreSQL

Host: localhost
Port: 5432
Database: flexprice
Username: flexprice
Password: flexprice123

ClickHouse

Host: localhost
Port: 9000 (native), 8123 (HTTP)
Database: flexprice
Username: flexprice
Password: flexprice123

Kafka

Bootstrap Server: localhost:29092
UI: http://localhost:8084 (with --profile dev)

API Authentication

The default development API key is:

API Key: 0cc505d7b917e0b1f25ccbea029dd43f4002edfea46b7f941f281911246768fe
Header: x-api-key

These credentials are for development only. Never use them in production environments.

Useful Commands

Common commands for managing your FlexPrice installation:

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

# Stop all services
make down

# Clean everything and start fresh
make clean-start

# View logs for specific services
docker compose logs -f flexprice-api
docker compose logs -f flexprice-consumer
docker compose logs -f flexprice-worker

Optional: Kafka UI

To enable the Kafka UI for easier topic management:

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

Access it at http://localhost:8084

Next Steps

• Configure FlexPrice for your environment
• Choose a deployment mode for production
• Scale your deployment for high availability

Troubleshooting

Docker Issues

1. Ensure Docker is running:

   docker info
   

2. Check container status:

   docker compose ps
   

3. View logs for a specific service:

   docker compose logs [service_name]
   

Database Connection Issues

Check if databases are healthy:

docker compose logs postgres
docker compose logs clickhouse

Kafka Issues

Verify Kafka is running and list topics:

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