Use this file to discover all available pages before exploring further.
The Workforce Intelligence & Execution OS local development environment consists of three concurrently running processes — the FastAPI backend, the Next.js 15 frontend, and the Celery background worker — backed by either a local SQLite database or PostgreSQL, and a Redis instance. This guide covers every step from prerequisites through environment configuration, service startup, database management, and resolving common development errors.
SQLAlchemy connection string. Comment out to use the SQLite fallback.
DATABASE_PUBLIC_URL
(empty)
Public-facing database URL for Railway or other cloud deployments
PGDATABASE
workforce_intelligence_utf8
PostgreSQL database name
PGHOST
localhost
PostgreSQL host
PGPORT
5432
PostgreSQL port
PGUSER
postgres
PostgreSQL user
PGPASSWORD
postgres
PostgreSQL password
PostgreSQL databases must use UTF-8 encoding to support emoji and Unicode content in messages. Create the database with:
CREATE DATABASE workforce_intelligence_utf8 WITH ENCODING 'UTF8' TEMPLATE template0 LC_COLLATE='C' LC_CTYPE='C';
To use SQLite for local development with zero database setup, comment out the DATABASE_URL line in your .env file. The backend automatically falls back to a local workforce_intelligence.db file.
From the apps/api directory with your virtual environment active:
alembic upgrade head
This creates all database tables and applies any pending schema migrations.
2
Seed the database (optional)
Load reference and sample data:
python seed.py
3
Bootstrap admin auto-creation
The API automatically seeds permissions and creates the bootstrap admin user on first startup using the BOOTSTRAP_ADMIN_EMAIL and BOOTSTRAP_ADMIN_PASSWORD values in your .env file. No manual step is needed.
From the apps/api directory with your virtual environment active:
celery -A app.worker worker --loglevel=info
The --pool=solo flag is required on Windows because Celery’s default prefork multiprocessing pool is not fully supported. On macOS and Linux, omit this flag.
Always ensure all three services (API, worker, Redis) are running before testing end-to-end flows. Many errors are caused by a partially started stack.
Symptom: The Celery worker fails to start or background jobs are not processed. Error message includes redis.exceptions.ConnectionError: Error 111 connecting to localhost:6379.Cause: The Redis server is not running, or REDIS_URL in .env is incorrect.Fix:
Start Redis: redis-server or docker run -d -p 6379:6379 redis
Verify the REDIS_URL in your .env matches where Redis is listening:
Symptom: SQL errors mentioning database is locked when performing write operations.Cause: SQLite does not support concurrent writes. When both the API server and the Celery worker attempt to write simultaneously, one process will be blocked.Fix: Restart both the API server and the Celery worker. For persistent concurrent write needs, switch to PostgreSQL by setting DATABASE_URL in your .env.
Symptom: JWT token signing fails; login returns 500 errors immediately after startup.Cause:APP_SECRET_KEY is still set to the placeholder value change-me-locally or is missing.Fix: Set a strong, unique secret in your .env:
Symptom: API requests from the frontend fail with Access-Control-Allow-Origin errors in the browser console.Cause: The frontend’s origin (http://localhost:3000) is not listed in CORS_ORIGINS.Fix: Ensure the frontend URL is included in .env:
