Operations
Upgrade, backup, and restore
Update containers and desktop apps while protecting databases, indexes, and uploads.An upgrade must keep application metadata, knowledge indexes, and uploaded files consistent. Container deployments need both database and volume protection. Desktop updates preserve version alignment across Web, API, and the Python sidecar by replacing the complete package.
Update Docker
git pull --ff-only
docker compose up -d --buildThis rebuilds services while preserving the default sagdata volume. Check the deployment afterward:
docker compose ps
docker compose logs --tail=200 api webDo not use docker compose down -v as a "clean reinstall" unless you have explicitly decided to delete all knowledge data permanently.
Back up a PostgreSQL deployment
Save at least two components before an upgrade:
pgdata: application metadata, relational records, and pgvector data.sagdata: uploaded files and the engine data directory.
The backup must represent a consistent point in time. The safest approach is to create a logical database backup and snapshot the file volume during a brief write pause.
Practice restoration in an independent environment. Verify sign-in, document counts, retrieval, citations, and file preview instead of checking only that containers start.
Update the desktop application
Desktop uses the stable GitHub Releases channel for full-package updates. Electron, Next.js, the Python API, and native dependencies share one release version and cannot be replaced independently.
Data is not stored in the installation directory:
| Platform | User data directory |
|---|---|
| macOS | ~/Library/Application Support/SAG/ |
| Windows | %APPDATA%\SAG\ |
An in-place installation and automatic update preserve these directories by default. The Windows uninstaller also preserves user data unless told otherwise.
Release integrity
Public releases include SHA256SUMS.txt. Use it to verify installer integrity after downloading. macOS artifacts should be signed and notarized. Windows may currently display an unknown-publisher warning.
Compatibility principles
- Use only non-draft published releases as stable update sources.
- Never move or reuse a version tag that has already been published.
- Web, API, and Desktop use one package version.
- Move between storage backends through configuration and a controlled migration, never by copying incompatible index directories directly.