gemma3-vllm-stack/docs/UPGRADE_NOTES.md

Upgrade Notes

Standard safe upgrade path

From repository root:

git pull
docker compose pull
./scripts/restart.sh

Then run smoke tests:

./scripts/test_api.sh
./scripts/test_ui.sh
python3 scripts/test_python_client.py

Versioning guidance

• Prefer pinning image tags in docker-compose.yml once your deployment is stable.
• Upgrading vLLM may change runtime defaults or engine behavior; check vLLM release notes before major version jumps.
• Keep GEMMA_MODEL_ID explicit in .env to avoid unintentional model drift.

Model upgrade considerations

When changing Gemma 3 variants (for example, from 1B to larger sizes):

• Verify host RAM and GPU memory capacity.
• Expect re-download of model weights and larger disk usage.
• Re-tune:
  • VLLM_MAX_MODEL_LEN
  • VLLM_GPU_MEMORY_UTILIZATION
• Re-run validation scripts after restart.

Backup recommendations

Before major upgrades, back up local persistent data:

mkdir -p backups
tar -czf backups/hf-cache-$(date +%Y%m%d-%H%M%S).tar.gz "${HOME}/.cache/huggingface"
tar -czf backups/open-webui-data-$(date +%Y%m%d-%H%M%S).tar.gz frontend/data/open-webui

If you use local predownloaded models:

tar -czf backups/models-$(date +%Y%m%d-%H%M%S).tar.gz models

Rollback approach

If a new image/model combination fails:

1. Revert docker-compose.yml and .env to previous known-good values.
2. Pull previous pinned images (if pinned by tag/digest).
3. Restart:

./scripts/restart.sh

4. Re-run smoke tests.