DocumentationBackups and upgrades

Backups and upgrades

Back up the database, files, and configuration, upgrade Feronavi, and restore data when needed.

Back up the whole instance

A recoverable backup includes the database, attachments and keys in application data volumes, and Compose and environment configuration. A database-only backup cannot restore attachments.

Backups can contain sensitive information and should be stored in controlled locations. If attachments use external storage, include that service’s data and configuration in your recovery plan.

Inspect the current instance

Record the current app image tag and service configuration, then check health:

docker compose ps
docker compose logs --tail=100 app worker

Use the backup utilities included in the product source after checking instructions and output locations for your version. Validate a restoration in a separate environment; check that both records and files can be recovered.

Plan the upgrade

  1. Read the target version’s changes and database migration requirements.
  2. Back up the database, data volumes, and configuration.
  3. Schedule a maintenance window to prevent concurrent writes.
  4. Obtain the target Compose configuration and compare service and database migration requirements.
  5. Set FERONAVI_VERSION in .env to the target app release, such as 0.1.0. The application and worker use the same image version.
  6. Pull the target images and update the services.
docker compose pull
docker compose up -d --wait
docker compose ps

If the database image or major version changes, follow the target version’s migration instructions first. Do not cross database major versions by changing an image tag alone.

Verify after upgrading

Check sign-in, project reads, a normal work-item edit, attachment downloads, notifications, and knowledge retrieval. Teams using MCP should also verify a read-only query and its access scope.

Review application and worker logs. A queued or running background job still needs its final business result checked.

Restore or roll back

After a database migration, an older application may not understand the new schema. Plan rollback around the complete pre-upgrade backup and version-specific recovery instructions. Verify in an isolated environment first.

After restoring, check both database records and attachment contents. Reopen team access once the business application is usable.

Type a keyword to search all documentation.