Skip to content

Setting Up Your Development Environment

This guide will walk you through setting up your development environment. Skip this tutorial if you already have a development environment set up.

Prerequisites

Python 3.11 or higher: If you haven't installed Python yet, download it from the official website.

Install uv

uv is a fast Python package manager and virtual environment tool. Install it once:

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

powershell -c "irm https://astral.sh/uv/install.ps1 | iex"

Verify the installation:

uv --version

Create a Project Directory

mkdir rag-project
cd rag-project

Create a Virtual Environment

Use uv to create a virtual environment:

uv venv --python 3.11

Activate the Virtual Environment

source .venv/bin/activate

.venv\Scripts\activate

After activation, your command prompt should be prefixed with (.venv).

Skip activation with uv run

Instead of activating the venv, you can prefix any command with uv run: 

uv run python my_script.py
uv run automatically manages the virtual environment for you.

Set Up Environment Variables (.env)

Store secrets and configuration in a .env file — never commit it to git.

Create .env in your project root:

# .env
OPENAI_API_KEY=sk-...
DATABASE_URL=postgresql://postgres:password@localhost:5432/ragdb

Add .env to .gitignore:

echo ".env" >> .gitignore

Install python-dotenv to load it automatically:

uv pip install python-dotenv

Load in your scripts:

from dotenv import load_dotenv
import os

load_dotenv()  # reads .env into os.environ

api_key = os.environ["OPENAI_API_KEY"]
database_url = os.environ["DATABASE_URL"]

Start pgvector with Docker

The vector database tutorials use PostgreSQL + pgvector. Start it with one Docker command:

docker run -d \
  --name pgvector \
  -e POSTGRES_PASSWORD=password \
  -e POSTGRES_DB=ragdb \
  -p 5432:5432 \
  pgvector/pgvector:pg16

Verify it's running:

docker ps | grep pgvector

Connect with psql to confirm:

psql postgresql://postgres:password@localhost:5432/ragdb -c "SELECT version();"

Docker required

Install Docker Desktop if you don't have it.

rag-project/
├── .env                  # secrets (gitignored)
├── .gitignore
├── rag/                  # application code
│   ├── __init__.py
│   ├── ingest.py         # chunking + embedding pipeline
│   ├── retrieve.py       # retrieval functions
│   └── generate.py       # prompt + LLM call
├── tests/                # unit and integration tests
│   ├── fixtures/         # sample documents, test JSONL
│   └── test_chunker.py
└── documents/            # source documents to index

Next step