Updating

Keep your self-hosted Quackback installation current with the latest features and security patches.

Before Updating

1. Check the Changelog

Review what's new in the release:

Visit the GitHub releases page
Read migration notes for breaking changes
Check compatibility requirements

2. Backup Your Data

Always backup before updating:

# Backup database
docker compose exec -T db pg_dump -U quackback quackback > backup_$(date +%Y%m%d).sql

# Backup uploads (if using local storage)
tar -czf uploads_$(date +%Y%m%d).tar.gz ./uploads

# Backup environment file
cp .env .env.backup

3. Check Disk Space

Ensure you have enough space for the update:

df -h

Updating with Docker Compose

Standard Update

# Pull the latest image
docker compose pull

# Stop current containers
docker compose down

# Start with new image
docker compose up -d

# Run any new migrations
docker compose exec app bun run db:migrate

Update to Specific Version

# Edit docker-compose.yml to specify version
# image: quackback/quackback:v1.2.0

docker compose pull
docker compose down
docker compose up -d
docker compose exec app bun run db:migrate

Updating from Git

If you cloned the repository:

# Fetch latest changes
git fetch origin

# Check current version
git describe --tags

# Update to latest
git pull origin main

# Or update to specific version
git checkout v1.2.0

# Rebuild
docker compose build

# Restart
docker compose down
docker compose up -d

# Run migrations
docker compose exec app bun run db:migrate

Migration Notes

Database Migrations

Migrations run automatically, but you can check status:

docker compose exec app bun run db:migrate:status

Rolling Back

If something goes wrong:

# Stop the application
docker compose down

# Restore database
docker compose exec -T db psql -U quackback quackback < backup_20240115.sql

# Restore previous version
docker compose pull quackback/quackback:v1.1.0
docker compose up -d

Zero-Downtime Updates

For production environments with multiple instances:

Using Rolling Updates

# Scale up new instances
docker compose up -d --scale app=4 --no-recreate

# Wait for health checks
sleep 30

# Remove old instances one by one
docker compose up -d --scale app=2

Using Blue-Green Deployment

Deploy new version to separate containers
Run health checks on new deployment
Switch load balancer to new containers
Shut down old containers

Automatic Updates

Using Watchtower

Automatically update containers:

# docker-compose.yml
services:
  watchtower:
    image: containrrr/watchtower
    volumes:
      - /var/run/docker.sock:/var/run/docker.sock
    command: --interval 86400 quackback

Caution: Automatic updates may cause unexpected downtime. Consider manual updates for production.

Version Policy

Semantic Versioning

Quackback follows semantic versioning:

Major (v2.0.0) — Breaking changes, migration required
Minor (v1.2.0) — New features, backwards compatible
Patch (v1.1.1) — Bug fixes, no breaking changes

Support Policy

Latest major version: Full support
Previous major version: Security patches only
Older versions: No support

Troubleshooting Updates

Migration Failed

If migrations fail:

# Check migration logs
docker compose exec app bun run db:migrate 2>&1

# Manual fix if needed
docker compose exec app bun run db:migrate:down
docker compose exec app bun run db:migrate

Container Won't Start

# Check logs
docker compose logs app

# Common issues:
# - Database connection timeout (wait for DB to be ready)
# - Missing environment variables (check .env)
# - Port conflicts (check if port is in use)

Performance Issues After Update

# Rebuild database indexes
docker compose exec db psql -U quackback -c "REINDEX DATABASE quackback;"

# Clear cache
docker compose exec app bun run cache:clear

Getting Help

If you encounter issues:

Check the GitHub issues
Join our Discord community
Email support (with support license)

Back to: Self-Hosting Overview

Updating

On this page