Skip to content
GitHub

Quick start

Follow these four steps to reach your local dashboard. The default stack uses PostgreSQL and Redis, with the API, web app and Celery worker running locally.

Working directory: the repository root, which contains pnpm-workspace.yaml. Run every command below there.

ToolRequirement
Node.js≥ 22.13; use Corepack to install the pnpm version pinned in package.json
Python≥ 3.11, with uv installed
DockerDocker is running and docker compose is available

终端窗口
docker compose -f docker-compose.dev.yml up -d

Check their status:

终端窗口
docker compose -f docker-compose.dev.yml ps

Expected result: both fba_postgres and fba_redis report healthy. On the first start, wait for their health checks before continuing.

2. Install dependencies and prepare configuration

Section titled “2. Install dependencies and prepare configuration”
终端窗口
pnpm install:all

This installs JavaScript and Python dependencies, Git hooks and Playwright Chromium. Continue when it finishes without errors and apps/api/.venv exists.

Copy the backend configuration, keeping an existing .env file:

终端窗口
cp -n apps/api/backend/.env.example apps/api/backend/.env

The example defaults match the containers above. If you already had a configuration file, check its database and Redis connections.

Keep DATABASE_PK_MODE='snowflake'. The seeds use snowflake IDs; switching to autoincrement or omitting this line makes initialization fail to find the admin account.

终端窗口
pnpm db:init

Follow the prompts to confirm the target and set a new password for admin. Keep this password for sign-in. Initialization also disables the sample test account; automation supplies the password through FBA_INIT_ADMIN_PASSWORD.

Expected result: the last message says the new database was stamped at the migration head. Check the revision:

终端窗口
pnpm db:current

The revision should be marked (head).

终端窗口
pnpm dev

Leave this terminal running and open http://127.0.0.1:8888.

Check these in order:

  1. The sign-in page shows a captcha image, confirming the frontend reaches the backend (captcha is enabled by default).
  2. Sign in as admin with the password you set during initialization and reach the dashboard.
  3. Refresh the page and remain signed in.

Your local environment is ready once all three work. Next time, check the containers are running and run pnpm dev.

Why does admin / 123456 fail?

Use the password chosen during initialization. admin / 123456 belongs to the live demo; initialization refuses to keep the seed password.

Can I disable the captcha locally?

Yes. After signing in, set LOGIN_CAPTCHA_ENABLED to false under System → Config; it takes effect immediately. Database settings can override .env; see captcha configuration troubleshooting.

For debugging, use the uuid from GET /api/v1/auth/captcha to read the answer in Redis:

终端窗口
docker exec fba_redis redis-cli --raw GET "fba:login:captcha:<uuid>"

Which ports are used? What if 8888 is occupied?
ServicePortStarted by
FastAPI (uvicorn, auto-reload)8088pnpm dev
React (Vite)8888pnpm dev
Celery worker with embedded beat—pnpm dev
PostgreSQL / Redis5432 / 6380docker compose

The frontend uses a fixed port: CORS, OAuth2 callbacks and the desktop dev URL all use 8888. If it is occupied, Vite fails; identify the process before deciding whether to stop it. For other startup failures, search the error text in the FAQ.

Can I use SQL Server, MySQL or S3?

Yes. Optional services are listed below; switching databases also requires changing DATABASE_* in .env.

ServiceSetup
SQL Serverdocker compose -f docker-compose.dev.yml --profile sqlserver up -d mssql; also install ODBC Driver 18 on the host
MySQLBring MySQL 8.x; set DATABASE_TYPE='mysql' and use utf8mb4
S3-compatible storage (RustFS)docker compose -f docker-compose.dev.yml --profile s3 up -d rustfs; set STORAGE_ENCRYPT_SECRET_KEY (generate with openssl rand -hex 32) before adding storage in the UI

Continue with Databases or File storage.