espiritismo-rag-system/BUILD.md

Build e Deployment Instructions

Prerequisites

• Docker and Docker Compose installed
• ~5GB free disk space
• 8GB RAM minimum
• CPU for model inference

Download the Model

Before building, download the Llama 3.2 3B quantized model:

# Download model (approximately 2GB)
cd backend
wget https://huggingface.co/MaziyarPanahi/Llama-3.2-3B-Instruct-GGUF/resolve/main/llama-3.2-3b-instruct-q4_0.gguf

# Place in models directory
mkdir -p models
mv llama-3.2-3b-instruct-q4_0.gguf models/

Alternatively, use GPT4All's built-in downloader when starting the service.

Environment Setup

1. Copy the environment template:

cp backend/.env.example .env

2. Edit .env and set your Telegram credentials:

TELEGRAM_BOT_TOKEN=your_bot_token_here
TELEGRAM_CHAT_ID=your_chat_id_here

To get your chat ID, create a bot with @BotFather on Telegram and send /start.

Build and Start

1. Build the containers:

docker-compose build

2. Start all services:

docker-compose up -d

Index the Books

After starting the services, index the 6 existing books:

docker-compose run --rm web python backend/scripts/index_books.py

This will:

• Load PDFs from the PDF/ directory
• Extract text chunks
• Generate embeddings
• Store in Qdrant

Access the Services

• Web Interface: http://localhost:8000
• Qdrant API: http://localhost:6333/dashboard
• Redis: localhost:6379

Create a Telegram Bot

1. Chat with @BotFather on Telegram
2. Send /newbot and follow instructions
3. Copy the bot token to .env

Schedule Messages

1. Open the web interface: http://localhost:8000
2. Click on "Agendar Mensagens"
3. Select date/time and optionally a specific book
4. Click "Adicionar Agendamento"

Stop the Services

docker-compose down

View Logs

# All services
docker-compose logs -f

# Specific service
docker-compose logs -f web
docker-compose logs -f celery
docker-compose logs -f celery-beat

Troubleshooting

Model Download Issues

If the model download fails:

# Download manually
cd backend/models
wget <model-url>

Qdrant Not Starting

# Remove existing volume
docker volume rm espiritismo_qdrant_data
# Restart
docker-compose up -d qdrant

Out of Memory

Reduce the number of workers or use a smaller model.

Import Errors

Rebuild with:

docker-compose build --no-cache web
docker-compose up -d web