Testing New Releases

When new features or fixes are released on GitHub, you will want to test them on your local machine before deploying to production. This guide walks you through the complete workflow.

Overview

The typical update workflow has three steps:

1. Pull the latest code from GitHub
2. Sync your environment (check for new .env variables)
3. Restart services (with or without rebuild)

# The complete workflow
git pull
# Check .env.example for new variables
just prod-up rebuild

---

Step 1: Pull the Latest Code

First, download the latest changes from GitHub:

# Navigate to your project folder
cd infoconnect-search-engine

# Pull the latest changes
git pull

You will see output showing what changed:

remote: Enumerating objects: 45, done.
remote: Counting objects: 100% (45/45), done.
Unpacking objects: 100% (30/30), done.
From github.com:your-org/infoconnect-search-engine
   a1b2c3d..e4f5g6h  main       -> origin/main
Updating a1b2c3d..e4f5g6h
Fast-forward
 app/api/routes/search.py | 12 ++++++++++++
 docker/Dockerfile         |  3 +++
 pyproject.toml            |  2 +-
 3 files changed, 16 insertions(+), 1 deletion(-)

Check What Changed

Before updating, you can see what will change without actually pulling:

# Preview changes (does not download them)
git fetch
git log HEAD..origin/main --oneline

This shows a list of commits that will be applied.

---

Step 2: Check for Environment Changes

New releases often add new configuration options. You need to sync your .env file with any new variables.

No .env File?

If you don't have a .env file yet, copy the example first:

cp .env.example .env

Then proceed below to customize any settings for your environment.

Compare Your .env with the Example

# Show differences between your .env and the example
diff .env .env.example

Look for lines starting with + — these are new variables in .env.example that you might need to add to your .env.

Common Environment Changes

Type of Change	What to Look For	Action Required
New features	New ENABLED variables	Add them to .env with your preferred setting
New AI models	New *_MODEL_NAME variables	Add them; models download automatically
New file types	Changes to ALLOWED_EXTENSIONS	Copy the updated list to support new formats (e.g., .pptx, .xlsx, .ppt, .xls)
Timeout changes	New or changed *_TIMEOUT_SEC	Add them if you want custom timeouts
API changes	New API_* settings	Update to match your security requirements

Quick Sync Method

If you want to see all variables side by side:

# Show only variable names from both files
echo "=== Your .env ==="
grep -E '^[A-Z_]+=' .env | sort
echo ""
echo "=== .env.example ==="
grep -E '^[A-Z_]+=' .env.example | sort

Important

Always review changes before copying variables. Some settings (like API_KEY_CLIENTS) should stay as your API key to client mapping, not be overwritten with example values.

---

Step 3: Choose the Right Restart Command

After pulling code, you need to restart the services. But should you do a simple restart or a full rebuild?

When to Use just prod-up (No Rebuild)

Use this when only application code changed (Python files, configuration):

just prod-up

Examples of code-only changes:

• Bug fixes in API routes
• New search features
• Changes to document processing logic
• Updates to Celery task handlers

The Docker containers will restart and load the new Python code automatically.

When to Use just prod-up rebuild

Use this when infrastructure or dependencies changed:

just prod-up rebuild

You need rebuild when:

Change Type	Why Rebuild?
pyproject.toml changed	New Python dependencies need installation
docker/Dockerfile changed	Container build process changed
docker-compose.yml changed	Service configuration or new services added
New system packages required	OS-level dependencies in Dockerfile
AI model changes requiring new libraries	Embedding or OCR library updates

How to Tell if You Need Rebuild

Check the files that changed in the git pull output:

• If you see pyproject.toml, Dockerfile, or docker-compose.yml → use rebuild
• If you only see .py files → simple restart is fine

Full Rebuild for Major Updates

For significant updates (like version bumps or dependency overhauls), do a clean rebuild:

# Stop everything and remove old containers
just prod-down

# Rebuild from scratch
just prod-up rebuild

This ensures no cached layers interfere with the new build.

---

Step 4: Verify the Update

After restarting, confirm everything works:

Check Service Status

just status

All services should show green checkmarks.

Test Core Functionality

# Test the search endpoint
just search-smoke

This sends a test query to verify the API is responding correctly.

Check API Documentation

Open http://localhost:8000/docs and verify:

• All expected endpoints are listed
• New endpoints appear (if the update added them)
• No error messages in the UI

---

Common Update Scenarios

Scenario 1: Minor Bug Fix

# Pull the fix
git pull

# Check if .env changed
diff .env .env.example

# Simple restart (just code changed)
just prod-up

# Verify
just status

Scenario 2: New Feature with Dependencies

# Pull the update
git pull

# Check what changed - you see pyproject.toml in the list
# Review and sync .env
diff .env .env.example
# Add any new variables to .env

# Rebuild required (dependencies changed)
just prod-up rebuild

# Verify
just status
just search-smoke

Scenario 3: New Environment Variables Only

# Pull the update
git pull

# Check .env differences - new variables added
diff .env .env.example
# Copy new variables to your .env

# Restart to pick up new config
just prod-up

# Verify
just status

Scenario 4: Major Version Update

# Pull the major update
git pull

# Stop everything cleanly
just prod-down

# Review all environment changes carefully
diff .env .env.example
# Update .env with new required variables

# Full rebuild
just prod-up rebuild

# Wait for startup, then verify
just status
just search-smoke

---

Troubleshooting Updates

Problem	Cause	Solution
Services fail to start after update	Missing new environment variables	Check diff .env .env.example and add missing variables
Import errors in logs	New dependencies not installed	Run just prod-up rebuild to install new packages
API returns errors	Database schema or config mismatch	Run just prod-down clean then just prod-up rebuild
New endpoints missing	Caching issue	Hard refresh browser (Ctrl+F5) or try incognito mode
Classification metadata missing	Classification disabled or category list empty	Check CLASSIFICATION_ENABLED and ALLOWED_CATEGORIES in .env
"Module not found" errors	Python dependencies out of sync	Run just prod-up rebuild
Disk space full	Accumulated Docker images and build cache	Run just prod-down clean to remove unused images and free space

Rollback If Something Goes Wrong

If the update breaks something, you can go back to the previous version:

# Stop current services
just prod-down

# Go back to previous commit
git log --oneline -5  # See recent commits
git reset --hard HEAD~1  # Go back one commit

# Restart with previous version
just prod-up

warning

git reset --hard discards all changes. Only use this if you have not made local modifications you want to keep.

---

Quick Reference

Update Checklist

# 1. Pull changes
git pull

# 2. Check if rebuild needed
# Look for: pyproject.toml, Dockerfile, docker-compose.yml changes

# 3. Sync environment
diff .env .env.example
# Add any new variables to .env

# 4. Restart
just prod-up          # For code-only changes
just prod-up rebuild  # For dependency/infrastructure changes

# 5. Verify
just status
just search-smoke

Decision Tree: Rebuild or Not?

---

What's Next

• Learn about configuration options you can customize
• Explore performance tuning and search filters
• Read about the architecture to understand how components interact