Local Installation

This guide walks you through running the full OpenModels platform on your local machine for development. The platform consists of a NestJS API, a Next.js web interface, PostgreSQL, Redis, and a Python-based telemetry worker.

Prerequisites

Make sure you have the following installed:

Verify your setup:

node --version    # v20.x or higher
python3 --version # 3.11 or higher
docker --version  # 24.x or higher
git --version     # 2.30 or higher

Clone the Repositories

OpenModels has two main repositories:

# Create a workspace directory
mkdir openmodels-dev && cd openmodels-dev
 
# Clone the public registry (models, providers, mappings)
git clone https://github.com/openmodels-run/openmodels.git
 
# Clone the platform (API, web, docs)
git clone https://github.com/openmodels-run/platform.git

Start Infrastructure

The platform requires PostgreSQL and Redis. Use Docker Compose to spin them up:

cd platform
docker compose up -d

This starts:

• PostgreSQL 15 on port 5432
• Redis 7 on port 6379

Verify the services are running:

docker compose ps

You should see both containers in a healthy state.

Environment Variables

Copy the example environment file and configure it:

cp .env.example .env

Key variables to set:

The defaults work out of the box with the Docker Compose setup.

Run the API

The NestJS API serves the model registry data and telemetry endpoints:

cd platform
 
# Install dependencies
npm install
 
# Run database migrations
npm run migration:run
 
# Seed the database with registry data (optional)
npm run seed
 
# Start the API in development mode
npm run dev

The API will be available at http://localhost:3000. Verify it’s running:

curl http://localhost:3000/api/health

Expected response:

{ "status": "ok" }

Run the Web Interface

The Next.js web interface provides model browsing, provider comparison, and telemetry dashboards:

cd platform/apps/web
 
# Install dependencies (if not already done from root)
npm install
 
# Start the dev server
npm run dev

The web interface will be available at http://localhost:3001.

Run the Docs Site

To run this documentation site locally:

cd docs
 
# Install dependencies
npm install
 
# Start the dev server
npm run dev

The docs site will be available at http://localhost:3040.

Run the Telemetry Worker (Optional)

The Python telemetry worker probes provider health and latency. It’s optional for most development work:

cd platform/workers/telemetry
 
# Create a virtual environment
python3 -m venv venv
source venv/bin/activate
 
# Install dependencies
pip install -r requirements.txt
 
# Start the worker
celery -A tasks worker --loglevel=info

Summary of Ports

Troubleshooting

Port conflicts

If a port is already in use, you’ll see an EADDRINUSE error. Either stop the conflicting process or change the port:

# Find what's using a port
lsof -i :3000
 
# Kill the process
kill -9 <PID>

For the docs site, you can change the port in docs/package.json or pass it directly:

npm run dev -- -p 3041

Database connection refused

If the API can’t connect to PostgreSQL:

1. Check Docker is running: docker compose ps
2. Verify the container is healthy: docker compose logs postgres
3. Ensure DATABASE_URL in .env matches the Docker Compose config
4. Try restarting: docker compose down && docker compose up -d

Redis connection issues

Similar to PostgreSQL — verify the Redis container is running:

docker compose logs redis
redis-cli ping  # Should return PONG

npm install fails

If you encounter dependency resolution issues:

# Clear the cache and retry
rm -rf node_modules package-lock.json
npm install

Python virtual environment issues

If the telemetry worker fails to start:

# Recreate the virtual environment
rm -rf venv
python3 -m venv venv
source venv/bin/activate
pip install -r requirements.txt

Migrations fail

If database migrations error out, the database might be in an inconsistent state:

# Reset the database (destroys all data)
docker compose down -v
docker compose up -d
 
# Re-run migrations
npm run migration:run

Next Steps

• Quickstart — Query the API to search and compare models
• Architecture Overview — Understand how the platform components fit together
• Adding a Model — Contribute a new model to the registry