Backups

About 664 wordsAbout 2 min

Backups

The stateful parts of a Spora install are storage/ and any agent templates you have authored. The full application state is in the database and the secret key. The rest of the filesystem can be rebuilt from a fresh clone + composer install + php bin/spora spora:install.

What to back up

PathWhat it isWhy
storage/database.sqliteSQLite database (the entire app state)The single source of truth for agents, conversations, credentials, plugin data, settings
storage/secret.keyThe libsodium master key (auto-generated by spora:install)Without it, you cannot decrypt any stored credentials — LLM API keys, plugin settings, etc.
storage/.plugins_stampPlugin loader cacheLets the plugin loader skip re-discovering installed plugins; safe to lose
config.php and .envOperator configurationDB credentials, Mercure URL, secret key path, mail transport, etc.
agent-templates/Custom agent templates you’ve addedOperator-authored; not recoverable from composer install — the bundled templates ship with spora-core/agent-templates
plugins/Locally installed pluginsTracked by Composer, but the composer.lock is the source of truth — plugins/ is reproducible from composer install

For MySQL, the database is not in storage/. Back it up via mysqldump (or your managed-database snapshot). The connection string lives in .env (SPORA_DB_*).

For Docker: storage/ is bind-mounted in docker/docker-compose.yml — back up the host-side path.

Backup strategy

A reasonable default for a small Spora install:

  1. Nightly full snapshot of storage/database.sqlite (or mysqldump), storage/secret.key, config.php, and .env, plus agent-templates/ when the project ships its own. Compress and store off-host.
  2. Off-host rotation: keep 7 daily, 4 weekly, 6 monthly. Test a restore quarterly.
  3. Secret key in a separate store — if your backup tool encrypts at rest, the secret key is in the same bucket. For higher assurance, put a copy of storage/secret.key in your password manager (it’s a 32-byte binary file — base64 it for storage).
  4. composer.lock in version control — the plugin install list is reproducible from a fresh checkout + composer install. Keep the lockfile in the operator repo, not just the framework repo.

What NOT to back up

PathWhy not
public/dist/Rebuilt from composer install (it’s the spora-frontend Composer package)
vendor/Rebuilt from composer install
node_modules/Rebuilt from npm install (only relevant in dev mode)
storage/spora.log, storage/php.logLogs are not state; rotate + archive them, but they’re not the backup target
.vuepress/.cache/, .vuepress/.temp/Build artefacts (docs site only)

Restore

# 1. Fresh checkout
composer create-project spora-ai/spora my-app
cd my-app

# 2. Restore config + .env + secret key
cp /backup/config.php /backup/.env .
cp /backup/secret.key storage/secret.key
chmod 600 storage/secret.key

# 3. Restore database
# SQLite:
cp /backup/database.sqlite storage/database.sqlite
# OR MySQL: restore the dump
mysql -u root -p spora < /backup/spora.sql

# 4. Reinstall plugins
composer install

# 5. Run migrations (idempotent)
php bin/spora spora:install

# 6. Verify
php bin/spora db:seed --check

If you lose storage/secret.key, you will need to re-enter every tool credential in the admin UI. The encrypted columns in the database will return errors until you do.

Cron example for SQLite

# /etc/cron.d/spora-backup
# Nightly snapshot, keep 14 days
15 2 * * * spora bash -c '
  set -e
  cd /var/www/spora
  ts=$(date +%Y%m%d-%H%M%S)
  targets="storage/database.sqlite storage/secret.key storage/.plugins_stamp config.php .env"
  # agent-templates/ is optional, so guard it — tar aborts on a missing path.
  if [ -d agent-templates ]; then targets="$targets agent-templates"; fi
  tar -czf /backups/spora/spora-$ts.tar.gz $targets
  find /backups/spora -name "spora-*.tar.gz" -mtime +14 -delete
'

What’s in storage/ exactly

From the framework reference:

storage/
├── database.sqlite   # Application database (SQLite default)
├── secret.key        # libsodium master key (auto-generated, 32 bytes binary)
├── spora.log         # Application logs (PSR-3, Monolog)
├── php.log           # PHP error/fatal logs
├── .plugins_stamp    # Plugin loader cache
└── .spora_plugin_catalog.json  # On-disk Packagist cache

The first three are state. The logs are not. The caches can be regenerated.

For the framework’s full env-var knobs that affect storage paths, see Environment variables → Logging.