Manual Upgrade (Docker Compose)

Manual upgrade procedure for self-managed Docker Compose deployments.

Overview

For Docker Compose deployments, customers are responsible for upgrading Chatty AI. This involves pulling new images from the GitHub Container Registry and restarting services.

Quick Upgrade Script

Download Upgrade Script

Save this script as upgrade-chatty.sh:

#!/bin/bash
#=================================================================
# Chatty AI Upgrade Script
# Upgrades Chatty AI to latest version
#=================================================================

set -e  # Exit on error

# Configuration
COMPOSE_DIR="${COMPOSE_DIR:-/root/chatty-app-deploy/deploy}"
BACKUP_DIR="${BACKUP_DIR:-/root/chatty-backups}"
TIMESTAMP=$(date +%Y%m%d_%H%M%S)

# Colors for output
RED='\033[0;31m'
GREEN='\033[0;32m'
YELLOW='\033[1;33m'
NC='\033[0m' # No Color

echo -e "${GREEN}==================================================================${NC}"
echo -e "${GREEN}Chatty AI Upgrade Script${NC}"
echo -e "${GREEN}==================================================================${NC}"
echo ""

# Navigate to compose directory
cd "${COMPOSE_DIR}"

# Check if deployment exists
if [ ! -f "docker-compose.yaml" ]; then
    echo -e "${RED}Error: docker-compose.yaml not found in ${COMPOSE_DIR}${NC}"
    exit 1
fi

# Show current versions
echo -e "${YELLOW}Current versions:${NC}"
docker images | grep chattyai-org | head -5
echo ""

# Confirmation
echo -e "${YELLOW}⚠️  This will upgrade Chatty AI to the latest version${NC}"
echo ""
read -p "Do you want to continue? (yes/no): " CONFIRM

if [ "${CONFIRM}" != "yes" ]; then
    echo "Upgrade cancelled"
    exit 0
fi

echo ""
echo -e "${YELLOW}Starting upgrade process...${NC}"
echo ""

# Step 1: Create backup
echo -e "${YELLOW}[1/6] Creating backup...${NC}"
mkdir -p "${BACKUP_DIR}"
BACKUP_PATH="${BACKUP_DIR}/pre-upgrade-${TIMESTAMP}"
mkdir -p "${BACKUP_PATH}"

# Backup database
docker compose exec -T db pg_dump -U chattyAdmin chattydb | gzip > "${BACKUP_PATH}/postgres-${TIMESTAMP}.sql.gz"

# Backup configuration
cp .env "${BACKUP_PATH}/.env"
cp docker-compose.yaml "${BACKUP_PATH}/docker-compose.yaml"

echo -e "${GREEN}✓ Backup created at ${BACKUP_PATH}${NC}"

# Step 2: Pull repository updates
echo -e "${YELLOW}[2/6] Pulling repository updates...${NC}"
cd ..
git pull origin main
cd deploy
echo -e "${GREEN}✓ Repository updated${NC}"

# Step 3: Pull new images
echo -e "${YELLOW}[3/6] Pulling new Docker images...${NC}"
docker compose pull
echo -e "${GREEN}✓ New images pulled${NC}"

# Step 4: Stop services
echo -e "${YELLOW}[4/6] Stopping services...${NC}"
docker compose down
echo -e "${GREEN}✓ Services stopped${NC}"

# Step 5: Start services with new images
echo -e "${YELLOW}[5/6] Starting services with new versions...${NC}"
docker compose up -d
echo -e "${GREEN}✓ Services started${NC}"

# Step 6: Wait for services to be ready
echo -e "${YELLOW}[6/6] Waiting for services to be ready...${NC}"
sleep 30

# Check service status
echo ""
echo -e "${YELLOW}Service status:${NC}"
docker compose ps

# Show new versions
echo ""
echo -e "${YELLOW}New versions:${NC}"
docker images | grep chattyai-org | head -5

echo ""
echo -e "${GREEN}==================================================================${NC}"
echo -e "${GREEN}Upgrade Complete!${NC}"
echo -e "${GREEN}==================================================================${NC}"
echo ""
echo -e "${YELLOW}Next steps:${NC}"
echo "1. Verify services are running: docker compose ps"
echo "2. Check logs: docker compose logs"
echo "3. Test login to Chatty AI"
echo "4. Verify functionality"
echo ""
echo "Backup location: ${BACKUP_PATH}"
echo ""

Make Script Executable

chmod +x upgrade-chatty.sh

Run Upgrade

# Default upgrade
./upgrade-chatty.sh

# Custom directories
COMPOSE_DIR=/path/to/deploy BACKUP_DIR=/path/to/backups ./upgrade-chatty.sh

Manual Upgrade Steps

If you prefer step-by-step manual upgrade:

Step 1: Pre-Upgrade Backup

CRITICAL: Always backup before upgrading!

cd /root/chatty-app-deploy/deploy

# Create backup directory
mkdir -p ~/chatty-backups/pre-upgrade-$(date +%Y%m%d)

# Backup database
docker compose exec db pg_dump -U chattyAdmin chattydb | \
  gzip > ~/chatty-backups/pre-upgrade-$(date +%Y%m%d)/postgres.sql.gz

# Backup configuration
cp .env ~/chatty-backups/pre-upgrade-$(date +%Y%m%d)/
cp docker-compose.yaml ~/chatty-backups/pre-upgrade-$(date +%Y%m%d)/

# Backup volumes (optional but recommended)
docker run --rm -v chatty-app_qdrant:/data -v ~/chatty-backups:/backup \
  ubuntu tar czf /backup/pre-upgrade-$(date +%Y%m%d)/qdrant.tar.gz /data

Step 2: Check Current Versions

# Check current image versions
docker images | grep chattyai-org

# Check running containers
docker compose ps

# Note current versions for comparison

Step 3: Pull Repository Updates

cd /root/chatty-app-deploy

# Pull latest deployment files
git pull origin main

# Check for changes
git log -5

# Review any docker-compose.yaml changes
git diff HEAD~1 deploy/docker-compose.yaml

Step 4: Review Release Notes

Check for breaking changes or new requirements:

# View README for changes
cat deploy/README.md

# Check ENV_DOCUMENTATION for new variables
cat deploy/ENV_DOCUMENTATION.md | grep -A 5 "NEW:"

Step 5: Update Environment Variables

If new variables are required:

cd deploy

# Compare with example
diff .env .env.example

# Add any new required variables
nano .env

Step 6: Pull New Docker Images

# Pull all new images
docker compose pull

# Verify new images downloaded
docker images | grep chattyai-org

Step 7: Stop Services

# Stop all services gracefully
docker compose down

# Verify all stopped
docker ps -a | grep chatty-app

Step 8: Start Services with New Images

# Start all services
docker compose up -d

# Watch startup logs
docker compose logs -f

Step 9: Verify Upgrade

# Check service status
docker compose ps

# Verify all services are healthy
docker compose ps | grep -v "Up"

# Check new versions
docker images | grep chattyai-org

Post-Upgrade Verification

1. Service Health Check

# All services running
docker compose ps

# Check resource usage
docker stats --no-stream

# View recent logs
docker compose logs --tail=100

2. Web Access Test

# Test Chatty AI
curl -k https://$(grep CHATTYAI_DOMAIN .env | cut -d= -f2)

# Test n8n
curl -k https://$(grep N8N_DOMAIN .env | cut -d= -f2)

# Test Databases
curl -k https://$(grep DATABASES_DOMAIN .env | cut -d= -f2)

3. Functionality Test

4. Database Integrity

# Check database connection
docker compose exec db psql -U chattyAdmin -d chattydb -c "SELECT version();"

# Check table counts
docker compose exec db psql -U chattyAdmin -d chattydb -c "\dt"

# Verify user data
docker compose exec db psql -U chattyAdmin -d chattydb -c "SELECT COUNT(*) FROM users;"

5. Qdrant Verification

# Check Qdrant health
curl http://localhost:6333/health

# List collections
curl http://localhost:6333/collections

# Check collection sizes
curl http://localhost:6333/collections | jq

Version-Specific Upgrade Notes

Upgrading to v4.x

# New environment variables required
echo "RAG_TOP_K=20" >> .env
echo "RAG_TOP_K_RERANKER=5" >> .env

# Restart services
docker compose down && docker compose up -d

Upgrading to v5.x

# Database migration required
docker compose exec db psql -U chattyAdmin -d chattydb -f /migrations/v5.sql

# Clear Qdrant cache
docker compose restart qdrant

Upgrading from v3.x to v4.x

# Major version upgrade - extra caution
# 1. Full backup required
./backup-chatty.sh

# 2. Review breaking changes
cat deploy/CHANGELOG.md

# 3. Update .env with new variables
# 4. Proceed with upgrade
./upgrade-chatty.sh

Troubleshooting

Upgrade Fails - Image Pull Error

# Check GitHub Container Registry access
docker login ghcr.io

# Verify deploy token
echo $GITHUB_TOKEN

# Manual pull
docker pull ghcr.io/chattyai-org/chatty-app:arm64

Services Won't Start After Upgrade

# Check logs
docker compose logs

# Check for configuration errors
docker compose config

# Verify environment variables
cat .env

# Try recreating containers
docker compose down
docker compose up -d --force-recreate

Database Migration Fails

# Check database logs
docker compose logs db

# Connect to database
docker compose exec db psql -U chattyAdmin -d chattydb

# Check migration status
SELECT * FROM schema_migrations;

# Rollback if needed
# See rollback procedure

Performance Issues After Upgrade

# Check resource usage
docker stats

# Check disk space
df -h

# Clear old images
docker image prune -a

# Restart services
docker compose restart

Version Mismatch

# Check all image versions
docker images | grep chattyai-org

# Remove old images
docker image prune -a

# Pull specific version
docker compose pull --ignore-pull-failures

Rollback Procedure

If upgrade fails, rollback to previous version:

# 1. Stop services
docker compose down

# 2. Restore configuration
cp ~/chatty-backups/pre-upgrade-*/env .env
cp ~/chatty-backups/pre-upgrade-*/docker-compose.yaml docker-compose.yaml

# 3. Restore database
gunzip -c ~/chatty-backups/pre-upgrade-*/postgres.sql.gz | \
  docker compose exec -T db psql -U chattyAdmin -d chattydb

# 4. Start services
docker compose up -d

# 5. Verify
docker compose ps

See Rollback Procedure for detailed steps.

Upgrade Checklist

Pre-Upgrade

Backup completed successfully
Backup verified (can restore if needed)
Release notes reviewed
Breaking changes identified
New environment variables added
Maintenance window scheduled
Users notified of downtime

During Upgrade

Post-Upgrade

Upgrade Best Practices

1. Always Backup First

# Full backup before every upgrade
./backup-chatty.sh

2. Test in Staging First

If you have a staging environment:

Upgrade staging first
Test thoroughly
Document any issues
Then upgrade production

3. Schedule During Off-Peak Hours

Upgrade during low-usage periods
Notify users in advance
Allow extra time for verification

4. Monitor After Upgrade

# Monitor logs for 24 hours
docker compose logs -f

# Watch resource usage
docker stats

# Check for errors
docker compose logs | grep -i error

5. Keep Old Images Temporarily

# Don't prune images immediately
# Keep for 7 days in case rollback needed

# After 7 days, clean up
docker image prune -a

Automated Upgrades

Create Upgrade Cron Job

NOT RECOMMENDED for production - manual upgrades preferred

# Edit crontab
crontab -e

# Add monthly upgrade (first Sunday at 3 AM)
0 3 1-7 * 0 /root/upgrade-chatty.sh >> /var/log/chatty-upgrade.log 2>&1

Upgrade via Portainer - For Portainer deployments
Rollback Procedure - How to rollback after upgrade
Backup Procedure - Creating backups
Restore Procedure - Restoring from backup

Overview​

Quick Upgrade Script​

Download Upgrade Script​

Make Script Executable​

Run Upgrade​

Manual Upgrade Steps​

Step 1: Pre-Upgrade Backup​

Step 2: Check Current Versions​

Step 3: Pull Repository Updates​

Step 4: Review Release Notes​

Step 5: Update Environment Variables​

Step 6: Pull New Docker Images​

Step 7: Stop Services​

Step 8: Start Services with New Images​

Step 9: Verify Upgrade​

Post-Upgrade Verification​

1. Service Health Check​

2. Web Access Test​

3. Functionality Test​

4. Database Integrity​

5. Qdrant Verification​

Version-Specific Upgrade Notes​

Upgrading to v4.x​

Upgrading to v5.x​

Upgrading from v3.x to v4.x​

Troubleshooting​

Upgrade Fails - Image Pull Error​

Services Won't Start After Upgrade​

Database Migration Fails​

Performance Issues After Upgrade​

Version Mismatch​

Rollback Procedure​

Upgrade Checklist​

Pre-Upgrade​

During Upgrade​

Post-Upgrade​

Upgrade Best Practices​

1. Always Backup First​

2. Test in Staging First​

3. Schedule During Off-Peak Hours​

4. Monitor After Upgrade​

5. Keep Old Images Temporarily​

Automated Upgrades​

Create Upgrade Cron Job​

Related Documentation​