Self-hosting Flexprice

Learn how to set up and run Flexprice on your own infrastructure

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.

This guide covers the backend (API and infrastructure). To run the dashboard UI, see Self-hosting the Frontend.

---

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:

Restart Flexprice Services (keep infrastructure running)

make restart-flexprice

Stop All Services

make down

Full Clean Start (destroys all data volumes)

make clean-start

Rebuild and Restart Only Flexprice Services

make build-image && make restart-flexprice

Re-run Seed Data (idempotent)

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:

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 (requires --profile dev)

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:

   Variable	Value
   baseUrl	http://localhost:8080/v1
   apiKey	sk_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:

Port 8080 already in use

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

401 Unauthorized on all API calls

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.

Redis connection refused (log warning)

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.

Database schema errors on fresh start

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

Docker Issues

1. Ensure Docker is running properly:

docker info

2. Check the status of all containers:

docker compose ps

3. View logs for a specific service:

docker compose logs -f flexprice-api
docker compose logs -f flexprice-consumer

4. If containers are in a bad state, do a full clean restart:

docker compose down -v
make dev-setup

Kafka Issues

1. Verify Kafka is running:

docker compose logs kafka

2. Check that all required topics exist:

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

3. Re-initialize topics if any are missing:

make init-kafka

ClickHouse migration errors

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:

• Check our GitHub Issues for similar problems
• Join our Slack community for real-time support
• Contact us at [e-mail]

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