Upgrading Karrio

This guide provides instructions on how to safely upgrade your self-hosted Karrio instance.

Before You Upgrade

Before upgrading your Karrio installation, it’s important to:

1. Backup your data: Always create backups of your database and configuration files before upgrading.
2. Check release notes: Review the release notes for any breaking changes.
3. Plan for downtime: The upgrade process will cause a few minutes of downtime.

Backing Up Your Data

It’s important to regularly back up your Karrio data:

Backup PostgreSQL database
1docker-compose exec db pg_dump -U postgres -d db > karrio_backup_$(date +%Y%m%d).sql
2
3# Backup configuration
4cp .env .env.backup.$(date +%Y%m%d)

Upgrading a Hobby Deployment

If you’ve used our one-click hobby deployment script, you can upgrade Karrio using the upgrade script:

1/bin/bash -c "$(curl -fsSL https://raw.githubusercontent.com/karrioapi/karrio/HEAD/bin/upgrade-hobby)"

The script will:

1. Ask for confirmation before proceeding
2. Check for named postgres volumes to avoid data loss
3. Download the latest docker-compose file
4. Pull the latest Karrio Docker images
5. Stop the current stack
6. Restart the stack with the new images

What to Expect During Upgrade

The upgrade process will:

1. Cause a few minutes of downtime
2. Preserve your database data and configurations
3. Apply any necessary database migrations automatically
4. Update all Karrio components to the latest version

Manually Upgrading a Docker Compose Deployment

If you’re running a manual Docker Compose installation, follow these steps to upgrade:

1. Navigate to your Karrio installation directory:

1cd /path/to/your/karrio

2. Update your local repository (if you’ve cloned it):

1git pull

3. Update the KARRIO_TAG in your .env file to the desired version:

Example
1KARRIO_TAG=2024.12.6

4. Pull the latest images:

1docker-compose pull

5. Stop the current stack:

1docker-compose down

6. Start the stack with the new images:

1docker-compose up -d

7. Monitor the logs to ensure everything is working correctly:

1docker-compose logs -f

Upgrading Specific Components

If you need to upgrade specific components only:

API and Worker

1docker-compose pull api worker
2docker-compose stop api worker
3docker-compose up -d api worker

Dashboard

1docker-compose pull dashboard
2docker-compose stop dashboard
3docker-compose up -d dashboard

Troubleshooting Upgrades

Database Migration Issues

If you encounter issues with database migrations:

Check the API logs for migration errors
1docker-compose logs api
2
3# Manually run migrations if needed
4docker-compose exec api karrio migrate

Version Compatibility

If you encounter compatibility issues between components, make sure all components are using the same version tag.

Rollback Procedure

If you need to rollback to a previous version:

1. Update your .env file with the previous version tag
2. Pull the previous version’s images:

1docker-compose pull

3. Restart the stack:

1docker-compose down
2docker-compose up -d

4. If you’ve made database changes, you may need to restore from your backup:

Stop the stack
1docker-compose down
2
3# Restore database (adjust parameters as needed)
4cat karrio_backup_YYYYMMDD.sql | docker-compose exec -T db psql -U postgres -d db
5
6# Start the stack
7docker-compose up -d

Checking Your Current Version

To check which version of Karrio you’re currently running:

1docker-compose exec api karrio version

Or check the image tags:

1docker ps --format "{{.Names}}: {{.Image}}"