Upgrading

How to update Tether to a newer version safely. The process is the same whether it is a minor patch or a major version.

Step 1 — Read the release notes

Before upgrading, check the GitHub releases page for the version you are upgrading to: github.com/atechlab-am/tether/releases

Look for:

• Breaking changes — any changes to the API, database schema, or .env format that require manual action
• Migration steps — SQL to run before or after updating the code
• New environment variables — check if there are new .env keys you need to add

Docker upgrade

bashCopy
# 1. Back up the database
docker exec tether-db mysqldump -u tether -ptether tether > backup-pre-upgrade-$(date +%Y%m%d).sql

# 2. Pull the latest code
git pull

# 3. Stop just the app container (keep the database running)
docker compose stop app

# 4. Rebuild the app image with the new code
docker compose build --no-cache app

# 5. Start the updated app
docker compose start app

# 6. Watch the logs for any errors
docker compose logs -f app
# Look for "Application startup complete"

Schema changes (new tables, new nullable columns with defaults) are applied automatically on startup. You do not need to run migration scripts for most upgrades.

Bare-metal upgrade

bashCopy
# 1. Back up the database
mysqldump -u tether -p tether > backup-pre-upgrade-$(date +%Y%m%d).sql

# 2. Pull the latest code
git pull

# 3. Activate the virtual environment and update dependencies
source .venv/bin/activate
pip install -r requirements.txt

# 4. Restart the service
sudo systemctl restart tether

# 5. Check the service started cleanly
sudo systemctl status tether
journalctl -u tether -n 50

Rolling back

If the upgrade causes problems:

bashCopy
# Docker rollback
git checkout HEAD~1        # revert to the previous version
docker compose build --no-cache app
docker compose start app

# Bare-metal rollback
git checkout HEAD~1
pip install -r requirements.txt
sudo systemctl restart tether

# If the schema changed and the rollback fails due to new columns:
# Restore the database backup instead
docker exec -i tether-db mysql -u tether -ptether tether < backup-pre-upgrade-20260531.sql

Staying notified of releases

Subscribe to GitHub release notifications:

1. Go to github.com/atechlab-am/tether
2. Click Watch → Custom → check Releases
3. You'll get an email whenever a new version is published