Local Development

Local Development

Prerequisites

• Node.js and npm
• Docker Desktop or Docker Engine with Compose
• Python 3.11+ for real Strategic Report generation

Start the application

git clone https://github.com/adm73/OpenBcon.git
cd OpenBcon
cp .env.example .env
npm install
npm run db:setup
npm run dev

npm run dev starts the Vite frontend and local API workflow. The frontend is served at http://localhost:5173; the Node API uses port 8787. The database setup starts PostgreSQL, migrates legacy state to MongoDB when needed, applies migrations, and loads demo data.

Run the AI service

In another terminal:

cd python-backend
python3 -m venv .venv
source .venv/bin/activate
pip install -r requirements.txt
uvicorn app.main:app --reload --host 0.0.0.0 --port 8010

For a no-key local flow, set OPENBCON_USE_MOCK_LLM=true in .env. For a real provider, set the appropriate server-side AI key and allowlisted provider host. Do not expose the Python service directly in production.

Useful commands

npm run dev:web # Vite only
npm run dev:api # Express API only
npm run dev:python # Python service helper
npm run db:up # start PostgreSQL
npm run db:migrate # apply migrations
npm run db:seed # load seed data
npm run db:down # stop local Compose services
npm run check # lint, tests, and production build

Named database volumes preserve local data. docker compose down --volumes deletes it, so use that only when intentionally resetting a development setup.