Skip to main content

​
Prerequisites

Before installing DecipherIt, ensure you have the following installed on your system:

​
Required Software

Node.js

Version 20 or higher required for the frontend

Python

Version 3.12 or higher required for the backend

PostgreSQL

Version 14 or higher for data storage

Docker

Optional, for containerized deployment

​
Package Managers

  • pnpm - Fast, disk space efficient package manager for Node.js
  • uv - Fast, disk space efficient package manager for Python
npm install -g pnpm
DecipherIt requires specific versions: Node.js 20+, Python 3.12+, and PostgreSQL 14+. Older versions may not work correctly.

​
Installation Steps

1

Clone the Repository

Clone the DecipherIt repository from GitHub:
git clone https://github.com/mtwn105/decipher-research-agent.git
cd decipher-research-agent
2

Set Up PostgreSQL Database

Create a PostgreSQL database for DecipherIt:
CREATE DATABASE decipher;
CREATE USER decipher_user WITH PASSWORD 'your_password';
GRANT ALL PRIVILEGES ON DATABASE decipher TO decipher_user;
Make note of your database credentials - you’ll need them for the environment variables.
3

Install Frontend Dependencies

Navigate to the client directory and install dependencies:
cd client
pnpm install
This will install all required packages including:
  • Next.js 15.3.2
  • React 19.0.0
  • Prisma for database ORM
  • Better Auth for authentication
  • Shadcn/ui components
4

Configure Frontend Environment

Copy the example environment file and configure it:
cp .env.example .env.local
Edit .env.local with your configuration. See the Environment Variables page for details.
5

Generate Prisma Client and Run Migrations

Generate the Prisma client and set up the database schema:
pnpm prisma generate
pnpm prisma migrate dev
This creates the necessary database tables and relationships.
6

Install Backend Dependencies

Navigate to the backend directory and set up the Python environment:
cd ../backend
uv venv
source .venv/bin/activate  # On Windows: .venv\Scripts\activate
uv sync
This installs all required packages including:
  • FastAPI for the API server
  • CrewAI for multi-agent workflows
  • Qdrant client for vector search
  • SQLAlchemy for database operations
  • MarkItDown for document processing
7

Configure Backend Environment

Copy the example environment file and configure it:
cp .env.example .env
Edit .env with your configuration. See the Environment Variables page for details.
8

Set Up Qdrant Vector Database

DecipherIt uses Qdrant for vector search. You can run it using Docker:
docker run -d \
  --name qdrant \
  -p 6333:6333 \
  -v $(pwd)/qdrant_storage:/qdrant/storage \
  qdrant/qdrant:latest
Or install it locally following the Qdrant installation guide.
9

Start the Development Servers

Open two terminal windows and start both servers:Terminal 1 - Frontend:
cd client
pnpm dev
Terminal 2 - Backend:
cd backend
source .venv/bin/activate  # On Windows: .venv\Scripts\activate
uv run uvicorn server:app --host 0.0.0.0 --port 8001
The frontend will be available at http://localhost:3000 and the backend API at http://localhost:8001.

​
Verify Installation

Once both servers are running, verify the installation:
  1. Frontend: Open your browser and navigate to http://localhost:3000
  2. Backend API: Navigate to http://localhost:8001/docs to view the API documentation
  3. Health Check: Navigate to http://localhost:8001/health to verify the backend is running

​
Next Steps

Configuration

Configure DecipherIt for your environment

Environment Variables

Complete environment variables reference

Docker Deployment

Deploy using Docker and docker-compose

Integrations

Set up Bright Data and other integrations

​
Troubleshooting

​
Database Connection Issues

If you encounter database connection errors:
  1. Verify PostgreSQL is running: systemctl status postgresql
  2. Check the DATABASE_URL in your .env.local and .env files
  3. Ensure the database user has the correct permissions

​
Port Already in Use

If port 3000 or 8001 is already in use: 
# Frontend - use a different port
pnpm dev -- -p 3001

# Backend - specify a different port
uv run uvicorn server:app --host 0.0.0.0 --port 8002

​
Qdrant Connection Failed

If the backend cannot connect to Qdrant:
  1. Verify Qdrant is running: docker ps or check the local service
  2. Check the QDRANT_API_URL in your backend .env file
  3. Ensure the port 6333 is not blocked by a firewall

Build docs developers (and LLMs) love

Get started for freeTalk to us