Skip to main content

​
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

  1. Install uv package manager:
curl -LsSf https://astral.sh/uv/install.sh | sh
  1. Clone the repository:
git clone https://github.com/josephrp/creditnexus.git
cd creditnexus
  1. 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
  1. Copy .env.example to .env and configure database connection:
cp .env.example .env
# Edit .env and set DATABASE_URL=postgresql://postgres:password@localhost/creditnexus
  1. 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
  1. 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
  1. Start the frontend:
cd client && npm run dev
  1. 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