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.
Before you start
Section titled “Before you start”| Tool | Requirement |
|---|---|
| Node.js | ≥ 22.13; use Corepack to install the pnpm version pinned in package.json |
| Python | ≥ 3.11, with uv installed |
| Docker | Docker is running and docker compose is available |
1. Start the database and Redis
Section titled “1. Start the database and Redis”docker compose -f docker-compose.dev.yml up -dCheck their status:
docker compose -f docker-compose.dev.yml psExpected 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:allThis 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/.envThe 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.
3. Initialize the development database
Section titled “3. Initialize the development database”pnpm db:initFollow 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:currentThe revision should be marked (head).
4. Start the app and sign in
Section titled “4. Start the app and sign in”pnpm devLeave this terminal running and open http://127.0.0.1:8888.
Check these in order:
- The sign-in page shows a captcha image, confirming the frontend reaches the backend (captcha is enabled by default).
- Sign in as
adminwith the password you set during initialization and reach the dashboard. - 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.
Common questions
Section titled “Common questions”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?
| Service | Port | Started by |
|---|---|---|
| FastAPI (uvicorn, auto-reload) | 8088 | pnpm dev |
| React (Vite) | 8888 | pnpm dev |
| Celery worker with embedded beat | — | pnpm dev |
| PostgreSQL / Redis | 5432 / 6380 | docker 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.
| Service | Setup |
|---|---|
| SQL Server | docker compose -f docker-compose.dev.yml --profile sqlserver up -d mssql; also install ODBC Driver 18 on the host |
| MySQL | Bring 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.
Where to go next
Section titled “Where to go next”- Feature overview: what the system can do.
- Sign-in and security: password policies and two-factor setup.
- Deployment: deploy prebuilt images to a server.
- Contributing: tests, branches and releases (in Chinese).