Stravia Docs

Backup and restore

A Stravia recovery set may include more than the database. Identify the actual database and artifact backends, preserve matching local files and configuration, and test recovery in an isolated environment.

Prerequisites

Before planning the copy, identify whether this instance uses SQLite or PostgreSQL and local or S3 artifact storage. For the SQLite copy procedure, schedule downtime so Server is fully stopped; do not use it as a live backup.

Identify what must be protected

  • Database: SQLite stores its database at <data-root>/db/gateway.db; PostgreSQL stores records remotely. Server does not silently fall back between backends.
  • Server configuration: The SQLite backend is selected through setup/database configuration; do not expect a SQLite URL in server.toml. If you start Server with --config pointing outside the data root, include that file separately. PostgreSQL connection configuration must also be recoverable.
  • Local files: Include local artifacts and imported Vendor plugin components under the data root.
  • External storage: S3-compatible artifact objects are outside the data root. Artifact backend settings are database settings, not server.toml; preserve the required database records and ensure the destination bucket and credentials are available.

A PostgreSQL dump does not include local artifacts or plugin files. Copying the data root does not include PostgreSQL records or external S3 objects.

Offline SQLite backup

For SQLite with local artifact storage, use an offline copy when Server is stopped. This is not a live SQLite backup method.

  1. Stop Server and confirm the process has exited.
  2. Copy the entire data root to a restricted backup location. Include hidden files and directories.
# Windows PowerShell; include hidden and system files
robocopy "C:\path\to\data-root" "D:\backups\stravia-data" /E /COPY:DAT /DCOPY:DAT
powershell
# Linux; the dot after the source includes hidden entries
cp -a /path/to/data-root/. /path/to/backup/stravia-data/
sh
  1. Record the Server release, backup time, data-root path, database backend, and any external --config path. Protect the backup and any copied configuration as sensitive data.

Validation boundary: A Windows smoke copied and restored a fresh SQLite/local-storage data root with Server stopped. It used an existing local Server 0.3.1 executable—not the official release archive—and did not establish binary identity. It did not cover real artifacts, provider configuration, PostgreSQL, S3, Docker, or live backup.

Restore a SQLite/local-data backup to a separate test directory

Use this procedure only if the original instance used SQLite and local artifact storage. A copied data directory is not isolated from external resources named by configuration: a PostgreSQL URL in server.toml, an external --config, or database-stored S3 settings can still point to production. If the backend or artifact destination is unclear, do not start the copied instance until external-resource access is isolated.

  1. Stop the original Server and confirm no process is writing to the data root. Confirm the source deployment used SQLite and local artifact storage; do not use this procedure for PostgreSQL or S3.
  2. Create a unique restore data-root path that does not already exist. Copy the entire backup, including hidden files, into it. Do not merge into an existing or production data root.
  3. If --config was used, inspect it before starting. Do not start the copy if it selects a production database or external resource. Use the same Server release as the backup for this isolated check.
  4. Start with explicit loopback binding and a port not used by another instance:
stravia-server.exe --host 127.0.0.1 --port 23472 --data-dir "C:\stravia-restored-data"
powershell
./stravia-server --host 127.0.0.1 --port 23472 --data-dir /path/to/stravia-restored-data
sh
  1. Verify setup/login, the expected restored database records, and local artifact availability. A ready process alone does not establish a successful restore. Test inference only when using a separately configured disposable provider; do not let the restored instance reach production providers.
  2. If a newer release cannot read the old data layout, stop the isolated instance and use the matching prior release before following the documented upgrade path. Do not point it at production data.

Success criteria

For the isolated SQLite/local-storage procedure, recovery is only confirmed after the copied instance starts from the new data root without contacting the original data location, the expected administrator can sign in, and the expected restored records and local files are present. A running process alone is not sufficient; do not use a live upstream request to test recovery. This guide's limited smoke did not include provider/model/key/history or real artifact data.

Troubleshoot a failed or unsafe restore

If the database backend, --config, or artifact destination might still reference production, do not start the copy; isolate its network and credentials first. If startup or sign-in fails, stop the test instance and preserve both the backup and original data unchanged while checking the release/layout and backend configuration. Do not repair by deleting or modifying the source database.

PostgreSQL and S3 recovery

For PostgreSQL, use PostgreSQL's backup/restore tools to restore into a new test database. Before starting Stravia, ensure the test instance has no network or credentials that allow access to the production database. Restore matching data-root files (including local artifacts and imported plugin components) separately. Configure the test connection through the deployment's actual configuration; do not assume all settings live in server.toml.

For S3-compatible artifacts, separately restore or replicate required objects into a new test bucket. Artifact backend settings are stored in the database; after database restore they may still reference the production bucket. Before starting Stravia, isolate network access and credentials from production and confirm the test configuration targets only the new bucket.

Plan a consistent recovery point

  1. Identify SQLite or PostgreSQL and local or S3 artifact storage.
  2. Stop Server for offline SQLite file copying; use the database provider's supported backup procedure for PostgreSQL.
  3. Preserve matching data-root files, external configuration files, database records, and external bucket objects as applicable.
  4. Record the release and paths needed to interpret the backup. Keep secrets and backup media access-restricted.
  5. Test the restore in isolation before relying on it.

Stravia's UI does not provide a verified one-click full-deployment backup-and-restore procedure. Do not infer a live-copy method or complete recovery from a database dump or data-root path alone.

Next steps

Review Upgrade before changing releases and Storage for data-root components and retention behavior.