Skip to content

Installation

Prerequisites

  • Python 3.11 or 3.13
  • Node.js 18+
  • PostgreSQL 14+ (with pg_mooncake columnar extension for demand_actuals)
  • Git

Step 1 — Clone and Configure

git clone <repo-url> ForecastAI2026.01
cd ForecastAI2026.01

Create the database configuration file:

cp files/config/config.yaml.example files/config/config.yaml

Edit files/config/config.yaml with your PostgreSQL connection details:

database:
  host: 127.0.0.1
  port: 5432
  database: forecastai        # your tenant database name
  user: postgres
  password: your_password
  schema: scenario
  sslmode: disable

Warning

Only the database: section belongs in this file. All other configuration is stored in the database. See Configuration Overview.

Step 2 — Python Dependencies

pip install -r files/requirements.txt

Key packages installed:

Package Version Purpose
fastapi ≥0.104 API framework
uvicorn[standard] ≥0.24 ASGI server
psycopg2-binary ≥2.9 PostgreSQL driver
pandas ≥2.0 Data processing
statsforecast ≥1.6 Statistical forecasting
dask[complete] ≥2023.10 Parallel processing
scipy ≥1.10 Distribution fitting
scikit-learn ≥1.3 ML preprocessing
anthropic ≥0.86 AI features (alerts, NLP segments)
python-jose ≥3.3 JWT authentication
orjson ≥3.11 Fast JSON serialisation

Optional (neural models):

Neural forecasting models require neuralforecast which has no prebuilt Windows binary:

pip install neuralforecast --no-deps
pip install torch lightning einops

Optional (TimesFM):

Google's TimesFM foundation model:

pip install timesfm

Then set the model path in the forecasting parameters via the UI.

Step 3 — Database Setup

Create the master database

CREATE DATABASE forecastai_master;

Run the master schema:

psql -U postgres -d forecastai_master -f files/DDL/master_schema.sql

Create the first tenant database

CREATE DATABASE forecastai;

Run the tenant schema:

psql -U postgres -d forecastai -f files/DDL/schema.sql
psql -U postgres -d forecastai -f files/DDL/supply_schema.sql
psql -U postgres -d forecastai -f files/DDL/allocation_schema.sql
psql -U postgres -d forecastai -f files/DDL/import_schema.sql
psql -U postgres -d forecastai -f files/DDL/pg_history_schema.sql

The schema creates all tables under the scenario schema (and the import staging schema) including parameters, item, site, demand_actuals, forecast_results, supply planning tables, allocation tables, and import staging tables.

Schema overview

Each tenant DB uses three PostgreSQL schemas: scenario (primary working schema — never drop), master (reference data + historization registry), and import (ETL staging — safe to drop and recreate). See Architecture → Three-Schema Architecture for details.

Seed default parameters

Start the API (step 5) and call:

curl -X POST http://localhost:8002/api/reload

This runs seed_parameters() which populates the scenario.parameters table with default values for all parameter types.

Step 4 — Frontend Dependencies

cd files/frontend
npm install

Step 5 — Running

# Windows: run the provided batch file
start.bat

This starts both the API and the frontend dev server. Alternatively:

# API only (port 8002)
cd files
python -m uvicorn api.main:app --host 127.0.0.1 --port 8002 --reload

# Frontend only (port 5173, in a second terminal)
cd files/frontend
npm run dev

Open http://localhost:5173 in your browser.

--reload and WSL

The --reload flag does NOT pick up file changes made from Windows when running Python in WSL. Use the manual restart approach instead. See Operations.

Background (production-like)

# API in background, logs to file
cd files
nohup python -m uvicorn api.main:app --host 127.0.0.1 --port 8002 --no-access-log \
  > /path/to/api_8002.log 2>&1 &

# Frontend production build
cd files/frontend
npm run build
# The built files are in files/frontend/dist/
# Serve them from the API or a web server (nginx, etc.)

Step 6 — First Login

The first admin user is created by the seed_default_admin() function which runs automatically at API startup. Check the startup logs for the default credentials or create the first user manually:

# Via API (no auth required for the first user on a fresh install)
curl -X POST http://localhost:8002/api/auth/users \
  -H "Content-Type: application/json" \
  -d '{"email":"admin@example.com","name":"Admin","password":"changeme","role":"admin"}'

Then log in at http://localhost:5173/login.

Environment Variables

An optional .env file in files/ is automatically loaded on startup:

# files/.env
DB_HOST=127.0.0.1
DB_PORT=5432
DB_NAME=forecastai
DB_USER=postgres
DB_PASSWORD=secret
DB_SCHEMA=scenario

# Authentication
JWT_SECRET=your-jwt-secret-key
JWT_ALGORITHM=HS256
JWT_EXPIRE_MINUTES=480

# OAuth (optional)
MICROSOFT_CLIENT_ID=...
MICROSOFT_TENANT_ID=...
GOOGLE_CLIENT_ID=...

# AI features (optional)
ANTHROPIC_API_KEY=sk-ant-...

Verifying the Installation

# Check API is running
curl http://localhost:8002/api/config

# Check API version
curl http://localhost:8002/docs   # opens interactive Swagger UI

# Check database connection
curl http://localhost:8002/api/items

# Reload data cache
curl -X POST http://localhost:8002/api/reload

Expected: all return HTTP 200.