HridaAI Upgrade & Migration

🔄 Update Guide

HridaAI Upgrade & Migration

Stay current without losing your data.

Your data (chats, users, settings, uploads) lives in a Docker volume or local database, not inside the container. HridaAI Upgrade & Migration means swapping the container image for a newer one. Your data stays exactly where it is.

📐 Choose Your Update Strategy

Before running any commands, decide how you want to track releases. The right choice depends on how you use HridaAI.

Scenario	Recommended approach
Personal / homelab	Use the :main tag and pull manually when you want the latest
Shared / team instance	Pin a specific version (e.g. :v0.8.6) and use Diun for update notifications
Production / critical	Pin a version, review release notes before upgrading, test in staging first

:main vs. Pinned Versions

The :main tag always points to the latest build. It's convenient but can include breaking changes without warning.

For stability, pin a specific release tag:

text

ghcr.io/hrida-ai/hrida-ai-studio:v1.0.0
ghcr.io/hrida-ai/hrida-ai-studio:v1.0.0-cuda
ghcr.io/hrida-ai/hrida-ai-studio:v1.0.0-ollama

⚡ Before You Update

• Back up your data (see Backup & Restore below). Especially important before releases with database migrations, which can be hard to undo.
• Check the release notes for breaking changes.
• Clear your browser cache after updating (Ctrl+F5 / Cmd+Shift+R) to avoid stale frontend assets.

⚠️ Running multiple workers or replicas?

Run migrations on a single instance first: set UVICORN_WORKERS=1 or ENABLE_DB_MIGRATIONS=false on all but one instance. See the Scaling guide for details.

🚀 Manual Update

Docker Run

bash

# 1. Stop and remove the container (data in the volume is preserved)
docker rm -f hrida-ai

# 2. Pull the latest image (or replace :main with a pinned version)
docker pull ghcr.io/hrida-ai/hrida-ai-studio:main

# 3. Recreate the container
docker run -d -p 3000:8080 \
-v hrida-ai:/app/backend/data \
-e HRIDAAI_SECRET_KEY="your-secret-key" \
--name hrida-ai --restart always \
ghcr.io/hrida-ai/hrida-ai-studio:main

For NVIDIA GPU support, add --gpus all to the docker run command.

Docker Compose

bash

docker compose pull
docker compose up -d

Make sure your docker-compose.yml includes HRIDAAI_SECRET_KEY:

yamldocker-compose.yml

services:
hrida-ai:
  image: ghcr.io/hrida-ai/hrida-ai-studio:main
  ports:
    - "3000:8080"
  volumes:
    - hrida-ai:/app/backend/data
  environment:
    - HRIDAAI_SECRET_KEY=your-secret-key
  restart: unless-stopped

volumes:
hrida-ai:

Python (pip)

bash

pip install -U hrida-ai

The -U flag upgrades to the latest version. Then restart the server:

bash

hrida-ai serve

⚠️ Set HRIDAAI_SECRET_KEY to avoid logout on every update

Without a persistent HRIDAAI_SECRET_KEY, a new key is generated each time the container is recreated, invalidating all sessions. Generate one with openssl rand -hex 32 and keep it across updates. See the Environment Variable Reference for details.

✅ Verify the Update

After updating, confirm everything is working:

1Check version in logs:
docker logs hrida-ai 2>&1 | head -20

2Load the UI at http://localhost:3000. You should see the login page.

3If the UI looks broken, clear your browser cache (Ctrl+F5 / Cmd+Shift+R).

4If you see migration errors in the logs, check the release notes for known issues and the Connection Errors troubleshooting page.

↩️ Rolling Back

If an update causes problems, you can go back to a previous version by pinning its tag.

Docker Run

bash

docker rm -f hrida-ai
docker pull ghcr.io/hrida-ai/hrida-ai-studio:v0.8.3
docker run -d -p 3000:8080 -v hrida-ai:/app/backend/data \
-e HRIDAAI_SECRET_KEY="your-secret-key" \
--name hrida-ai --restart always \
ghcr.io/hrida-ai/hrida-ai-studio:v0.8.3

Docker Compose

Change the image tag in your docker-compose.yml:

yaml

image: ghcr.io/hrida-ai/hrida-ai-studio:v0.8.3

Then:

bash

docker compose pull
docker compose up -d

Python (pip)

bash

pip install hrida-ai==0.8.3
hrida-ai serve

⚠️ Database migrations are one-way

If the version you updated to ran a database migration, rolling back the container does not undo the migration. The older version may not work with the newer database schema. In that case, you need to restore from a backup taken before the update. For database-specific recovery, see the Manual Database Migration guide.

🔔 Stay Notified About Updates

Instead of checking manually, use a tool to monitor for new releases. Options are listed from safest to most hands-on.

💡 Recommendation

Production / critical systems: Diun (notification-only) + manual updates
Managed environments: WUD (visual dashboard + manual trigger)
Homelabs / personal use: Watchtower (fully automated)

Feature	Diun	WUD	Watchtower
Auto-updates containers	❌	❌ (manual via UI)	✅
Web interface	❌	✅	❌
Notifications	✅	✅	✅
Docker 29+	✅	✅	✅ (forks)
Resource usage	Very Low	Medium	Low

Diun

Notification-only. Alerts you when updates are available (email, Slack, Telegram, etc.) without touching your containers. You decide when and how to update.

yamldocker-compose.yml

services:
diun:
  image: crazymax/diun:latest
  container_name: diun
  volumes:
    - /var/run/docker.sock:/var/run/docker.sock:ro
    - ./data:/data
  environment:
    - TZ=America/New_York
    - LOG_LEVEL=info
    - DIUN_WATCH_WORKERS=10
    - DIUN_WATCH_SCHEDULE=0 */6 * * *  # Every 6 hours
    - DIUN_PROVIDERS_DOCKER=true
    - DIUN_NOTIF_MAIL_HOST=smtp.gmail.com
    - DIUN_NOTIF_MAIL_PORT=587
    - DIUN_NOTIF_MAIL_USERNAME=your-email@gmail.com
    - DIUN_NOTIF_MAIL_PASSWORD=your-app-password
    - DIUN_NOTIF_MAIL_FROM=your-email@gmail.com
    - DIUN_NOTIF_MAIL_TO=your-email@gmail.com
  restart: unless-stopped

See Diun documentation for full setup and notification options.

What's Up Docker (WUD)

Web UI for monitoring container updates and triggering them manually. See WUD documentation for setup.

Watchtower

Fully automated. Pulls new images and recreates containers without intervention.

⚠️ Warning

The original containrrr/watchtower is no longer maintained and fails with Docker 29+. Use the nicholas-fedor/watchtower fork instead.

⚠️ Warning

Automated updates can break your deployment if a release includes breaking changes or database migrations. Review release notes before auto-updating production systems, and always have a backup.

One-time update:

bash

docker run --rm \
-v /var/run/docker.sock:/var/run/docker.sock \
nickfedor/watchtower --run-once hrida-ai

Continuous (check every 6 hours):

bash

docker run -d --name watchtower --restart unless-stopped \
-v /var/run/docker.sock:/var/run/docker.sock \
nickfedor/watchtower --interval 21600 hrida-ai

Set WATCHTOWER_CLEANUP=true to auto-remove old images. See Watchtower docs for scheduling, notifications, and monitor-only mode.

💾 Backup & Restore

All data lives in the hrida-ai Docker volume, including:

• Database: chats, users, settings, admin configuration
• Uploaded files: documents, images, knowledge base content
• Generated content: image generation outputs, exported data

Backup

bash

docker run --rm -v hrida-ai:/data -v $(pwd):/backup \
alpine tar czf /backup/hridaai-$(date +%Y%m%d).tar.gz /data

Back up before every update and on a regular schedule (daily or weekly, depending on how actively you use HridaAI).

Restore

⚠️ Caution

The restore command deletes everything in the volume before extracting the backup. Make sure you're restoring the right file.

bash

docker stop hrida-ai
docker run --rm -v hrida-ai:/data -v $(pwd):/backup \
alpine sh -c "rm -rf /data/* && tar xzf /backup/hridaai-YYYYMMDD.tar.gz -C /"
docker start hrida-ai

Replace YYYYMMDD with the actual date of your backup file.

For database-specific recovery, see the Manual Database Migration guide.

📚 Related Guides

Deployment & Scaling

Multi-worker and multi-instance deployments

→

Connection Errors

Troubleshooting post-update connectivity

→

Env Variable Reference

All configuration options including HRIDAAI_SECRET_KEY

→

Release Notes

Changelog for every version

→