Flagent Quick Start Guide

1

Option 1: Docker (Recommended)

Самый быстрый способ запустить Flagent - использовать Docker образ. Не требует установки зависимостей или настройки базы данных.

Step 1: Pull Docker Image

docker pull ghcr.io/maxluxs/flagent

Step 2: Run Container

Образ по умолчанию использует SQLite (файл в контейнере). Для входа в UI нужны admin-учётные данные и JWT secret. Минимальный запуск:

docker run -d -p 18000:18000 \
  -e FLAGENT_ADMIN_EMAIL=admin@local \
  -e FLAGENT_ADMIN_PASSWORD=admin \
  -e FLAGENT_JWT_AUTH_SECRET=change-me-min-32-chars-for-dev-only \
  -v flagent-data:/data \
  ghcr.io/maxluxs/flagent

-v flagent-data:/data — данные SQLite сохраняются между перезапусками. Без тома данные теряются при остановке контейнера.

Step 3: Open Flagent UI

Откройте браузер и перейдите на:

http://localhost:18000

Step 4: Default Credentials

Если аутентификация включена, используйте:

Email: admin@local

Password: admin

Step 5: Verify Installation

Проверьте, что сервер работает:

curl http://localhost:18000/api/v1/health

Должен вернуться JSON с информацией о состоянии сервера.

2

Option 2: Docker Compose

Для полной настройки с PostgreSQL используйте Docker Compose. Это обеспечивает персистентность данных и готовность к production.

Step 1: Clone Repository

git clone https://github.com/MaxLuxs/Flagent.git
cd Flagent

Step 2: Start Services

docker compose up -d

Это запустит Flagent и PostgreSQL в отдельных контейнерах.

Step 3: Access Services

Flagent UI: http://localhost:18000

API: http://localhost:18000/api/v1

Swagger UI: http://localhost:18000/docs

3

Option 3: From Source

Соберите и запустите Flagent из исходного кода для разработки и кастомизации.

Step 1: Prerequisites

JDK 21+ Для компиляции и запуска Kotlin кода

Gradle 9.0 Система сборки проекта

Database PostgreSQL, MySQL или SQLite

Step 2: Clone Repository

git clone https://github.com/MaxLuxs/Flagent.git
cd Flagent

Step 3: Build Project

./gradlew build

Это соберет все модули и запустит тесты.

Step 4: Configure Environment

Обязательно задайте базу данных и учётные данные админа (без них вход в UI даст «Admin credentials not configured»):

SQLite (для теста)

export FLAGENT_DB_DBDRIVER=sqlite3
export FLAGENT_DB_DBCONNECTIONSTR=flagent.sqlite
export FLAGENT_ADMIN_EMAIL=admin@local
export FLAGENT_ADMIN_PASSWORD=admin
export FLAGENT_JWT_AUTH_SECRET=dev-secret-min-32-characters-long
export PORT=18000

PostgreSQL

export FLAGENT_DB_DBDRIVER=postgres
export FLAGENT_DB_DBCONNECTIONSTR=jdbc:postgresql://localhost:5432/flagent?user=postgres&password=postgres
export FLAGENT_ADMIN_EMAIL=admin@local
export FLAGENT_ADMIN_PASSWORD=admin
export FLAGENT_JWT_AUTH_SECRET=dev-secret-min-32-characters-long
export PORT=18000

MySQL

export FLAGENT_DB_DBDRIVER=mysql
export FLAGENT_DB_DBCONNECTIONSTR=jdbc:mysql://localhost:3306/flagent?user=root&password=root
export FLAGENT_ADMIN_EMAIL=admin@local
export FLAGENT_ADMIN_PASSWORD=admin
export FLAGENT_JWT_AUTH_SECRET=dev-secret-min-32-characters-long
export PORT=18000

Подробнее: Configuration.

Step 5: Run Backend

./gradlew :backend:run

Сервер запустится на http://localhost:18000

Next Steps

После успешного запуска Flagent вы можете:

1. Create Your First Flag

Используйте UI или API для создания первого feature flag

Open UI

2. Try Evaluation API

Протестируйте evaluation API через curl или Swagger UI

curl --request POST \
  --url http://localhost:18000/api/v1/evaluation \
  --header 'content-type: application/json' \
  --data '{
    "entityID": "user-123",
    "entityType": "user",
    "entityContext": {
      "state": "NY",
      "tier": "premium"
    },
    "flagID": 1,
    "enableDebug": true
  }'

3. Connect SDK

Интегрируйте Flagent SDK в ваше приложение

View SDKs

4. Explore Documentation

Изучите полную документацию для продвинутых возможностей

View Docs

Troubleshooting

Port Already in Use

Если порт 18000 уже занят, измените его через переменную окружения:

export PORT=18001
docker run -it -p 18001:18001 -e PORT=18001 ghcr.io/maxluxs/flagent

Database Connection Issues

Убедитесь, что строка подключения к БД правильная и база данных доступна. Проверьте логи контейнера для деталей.

Authentication Issues

Если включена аутентификация, используйте правильные credentials. По умолчанию: admin@local / admin. Проверьте настройки через переменные окружения.

Full troubleshooting guide (First Run)