Skip to main content

Documentation Index

Fetch the complete documentation index at: https://docs.flexprice.io/llms.txt

Use this file to discover all available pages before exploring further.

You can run Flexprice on your own infrastructure in several ways. We organize self-hosting by provider so you can pick the option that fits your environment and add more providers over time.

​
Self-hosting options

Docker Compose

Run Flexprice locally or on a single server with Docker Compose. Best for development and small deployments.

AWS

Deploy Flexprice on AWS with ECS, RDS, MSK, and EKS. Production-ready, scalable setup.

​
Docker Compose

The fastest way to run Flexprice on your own machine or a single server is with Docker Compose.

​
Prerequisites

Before you begin, make sure you have the following installed:
Golang 1.23+
Docker and Docker Compose (Docker Desktop, OrbStack, or Podman Desktop all work)
make (pre-installed on macOS/Linux; on Windows use WSL or install via chocolatey)
One of these supported platforms:
  • Linux-based environment
  • macOS (Darwin)
  • WSL under Windows
You do not need psql, kafka-cli, or any other database client installed locally. All database operations run inside Docker containers via docker compose exec.

​
Quick Setup with Docker Compose

The easiest way to get started is using our automated setup command: 
# Clone the repository
git clone https://github.com/flexprice/flexprice
cd flexprice

# Set up the complete development environment
make dev-setup
This single command takes care of everything you need to get started:
  1. Starting all required infrastructure (PostgreSQL, Kafka, ClickHouse, Temporal)
  2. Building the Flexprice application image
  3. Running database migrations (PostgreSQL via Ent ORM + ClickHouse) and initializing Kafka topics
  4. Seeding default tenant and environment data
  5. Starting all Flexprice services (API, Consumer, Worker)

​
Default API Key

After setup, use the following key to authenticate local API requests: 
sk_local_flexprice_test_key
Pass it in the x-api-key request header: 
curl -H "x-api-key: sk_local_flexprice_test_key" http://localhost:8080/v1/customers
The key is pre-configured in internal/config/config.yaml. Entity tables are created entirely by the Ent ORM layer — the Postgres migration files only bootstrap schemas, extensions, and stored functions.

​
Accessing Services

Once setup is complete, you can access:

Flexprice API

http://localhost:8080

Temporal UI

http://localhost:8088

Kafka UI

http://localhost:8084 (requires --profile dev)

ClickHouse HTTP

http://localhost:8123
The Kafka UI requires the dev profile:
docker compose --profile dev up -d kafka-ui

​
Useful Commands

Here are some common commands you might need during development: 
make restart-flexprice

make down

make clean-start

make build-image && make restart-flexprice

make seed-db

​
Running Without Docker (API only)

If you prefer to run the application binary directly while keeping infrastructure in Docker: 
# Start required infrastructure
docker compose up -d postgres kafka clickhouse temporal temporal-ui

# Run migrations
make migrate-postgres migrate-clickhouse migrate-ent seed-db init-kafka

# Run the application locally
go run cmd/server/main.go

​
Connection Details

Use these credentials to connect to the various services:
  • Host: localhost
  • Port: 5432
  • Database: flexprice
  • Username: flexprice
  • Password: flexprice123
  • Host: localhost
  • Port: 9000 (native) / 8123 (HTTP)
  • Database: flexprice
  • Username: flexprice
  • Password: flexprice123

​
API Documentation

Flexprice provides comprehensive API documentation in OpenAPI 3.0 format.

​
Setting up Postman

  1. Open Postman
  2. Click on Import in the top left
  3. Select Import File
  4. Choose docs/swagger/swagger-3-0.json
  5. Click Import
  6. Create a new environment for local development:
    VariableValue
    baseUrlhttp://localhost:8080/v1
    apiKeysk_local_flexprice_test_key
Configure the collection to send x-api-key: {{apiKey}} as a header on every request.

​
Troubleshooting

If you encounter issues during setup or operation, try these troubleshooting steps:
Another process (e.g. a previously running local Flexprice binary) may be bound to port 8080 and intercepting requests before Docker’s port mapping.
# Find and kill the conflicting process
lsof -ti :8080 | xargs kill -9
Then restart the API container:
docker compose restart flexprice-api
The API key in your request does not match the configured key. For local development use:
curl -H "x-api-key: sk_local_flexprice_test_key" http://localhost:8080/v1/customers
If you changed the key in config.yaml, remember the config stores the SHA-256 hash of the raw key, not the key itself. The middleware hashes the incoming key before lookup.
You may see log lines like:
Failed to create Redis client: dial tcp [::1]:6379: connect: connection refused
This is non-fatal for local development. Redis is optional — it powers response caching, which falls back gracefully when unavailable. The API continues to work normally.
All entity tables (customers, plans, subscriptions, etc.) are managed exclusively by the Ent ORM migration layer. The Postgres migration files (migrations/postgres/) only create:
  • Schemas and the uuid-ossp extension (V0__init.sql)
  • Stored functions for invoice/billing sequences (V2_invoice_sequences.up.sql)
If you see relation does not exist errors, ensure you ran make migrate-ent after starting Postgres:
make migrate-ent
make seed-db
  1. Ensure Docker is running properly:
docker info
  1. Check the status of all containers:
docker compose ps
  1. View logs for a specific service:
docker compose logs -f flexprice-api
docker compose logs -f flexprice-consumer
  1. If containers are in a bad state, do a full clean restart:
docker compose down -v
make dev-setup
  1. Verify Kafka is running:
docker compose logs kafka
  1. Check that all required topics exist:
docker compose exec kafka kafka-topics --bootstrap-server kafka:9092 --list
  1. Re-initialize topics if any are missing:
make init-kafka
ClickHouse migrations use standard MergeTree engine for local/single-node compatibility. If you see engine-related errors, ensure you are running the open-source ClickHouse image (not ClickHouse Cloud) as specified in docker-compose.yml.To re-run ClickHouse migrations:
make migrate-clickhouse

​
Need Help?

If you’re still experiencing issues after trying the troubleshooting steps, please:

​
Additional Resources

Contribution Guidelines

Learn how to contribute to Flexprice

API Documentation

Explore our API documentation

Code of Conduct

Our community guidelines

Flexprice Website

Visit our official website