Installation

Detailed installation instructions for CreditNexus

System Requirements

• Python: 3.11 or higher
• Node.js: 20.x or higher
• PostgreSQL: 14 or higher
• Operating System: Linux, macOS, or Windows

Backend Installation

Using uv (Recommended)

1. Install uv package manager:

curl -LsSf https://astral.sh/uv/install.sh | sh

2. Clone the repository:

git clone https://github.com/josephrp/creditnexus.git
cd creditnexus

3. Sync dependencies:

uv sync

Database Setup

1. Create a PostgreSQL database:

Windows:

# Start PostgreSQL service using the psql client - use your own path
"C:\Program Files\PostgreSQL\18\bin\psql.exe" -U postgres -c "CREATE DATABASE creditnexus;"

Linux/macOS:

# Start PostgreSQL service
sudo systemctl start postgresql  # Linux
# or
brew services start postgresql@XX  # macOS

# Create database
createdb creditnexus

Or using Docker:

docker run --name creditnexus-postgres -e POSTGRES_PASSWORD=yourpassword -e POSTGRES_DB=creditnexus -p 5432:5432 -d postgres

2. Copy .env.example to .env and configure database connection:

cp .env.example .env
# Edit .env and set DATABASE_URL=postgresql://postgres:password@localhost/creditnexus

3. Run migrations:

uv run alembic upgrade head

This will create all necessary tables (documents, workflows, policy_decisions, users, etc.) based on the migration files in alembic/versions/.

Frontend Installation

1. Navigate to client directory:

cd client

2. Install dependencies:

npm install

Environment Configuration

Copy .env.example to .env and configure your settings:

cp .env.example .env
# Edit .env with your configuration

The .env.example file contains all available configuration options with documentation. Key variables include:

# Database
DATABASE_URL=postgresql://user:password@localhost/creditnexus

# LLM Configuration
LLM_PROVIDER=openai
LLM_MODEL=gpt-4o
OPENAI_API_KEY=sk-...

# Policy Engine
POLICY_ENABLED=true
POLICY_RULES_DIR=app/policies

# Authentication
JWT_SECRET_KEY=your-secret-key
JWT_ALGORITHM=HS256

📖 Complete Configuration Guide: See Configuration Documentation for all available environment variables and detailed setup instructions.

Verification

1. Start the backend:

uv run python server.py

2. Start the frontend:

cd client && npm run dev

3. Verify installation by accessing http://localhost:5173

Troubleshooting

Common Issues

Database Connection Error

• Verify PostgreSQL is running
• Check DATABASE_URL in .env file (copy from .env.example if needed)
• Ensure database exists
• Run migrations: uv run alembic upgrade head

LLM API Errors

• Verify API keys are set correctly
• Check network connectivity
• Review rate limits

Frontend Build Errors

• Clear node_modules and reinstall
• Check Node.js version (20+)
• Verify all dependencies are installed