Backups and restore

A self-hosted Nodaro is backed up with one command and restored with another. The backup archive holds everything the stack cannot regenerate: the database, your media, the instance encryption key and your .env. The restore is also the only way to downgrade, because the database migrations only move forward. Returning to an earlier version means restoring the backup you took before the update.

What a backup contains

tools/community-backup.sh writes one tar.gz archive:

Redis is left out on purpose: it holds only short-lived job state.

Take a backup

From your install directory, where docker-compose.community.yml is, with the stack running:

tools/community-backup.sh
# -> ./backups/nodaro-backup-<date>-v<version>.tar.gz

The script prints what went into the archive. If the encryption key is missing, it says so loudly and exits with an error, so a scheduled job notices. That archive cannot restore your provider keys.

The database dump is always consistent. Media written while the backup runs may miss the archive. For a guaranteed-consistent media snapshot, stop the app first:

docker compose -f docker-compose.community.yml stop nodaro

On Windows, run the scripts from Git Bash, the shell that Git for Windows installs. PowerShell and the bash of WSL break the container paths.

When to back up

Before every major version update, where the first number changes, and on whatever schedule your data deserves. A cron line works as it is:

0 3 * * * cd /path/to/install && tools/community-backup.sh >> backup.log 2>&1

Restore a backup

tools/community-restore.sh backups/nodaro-backup-<date>-v<version>.tar.gz

The restore replaces the database and the media with the archive's contents, so it asks you to type RESTORE before it touches anything. Then it:

1. Stops the app and the database clients, auth and rest, because their open connections would block the restore.
2. Restores Postgres and checks that it works, instead of trusting exit codes. Some harmless messages from the Supabase image are expected and printed.
3. Restores the media and checks that the buckets are back and MinIO is healthy. Then it restores the encryption key and checks its size on the volume. Then it restores your .env, after saving any existing .env aside. A failed check stops the script before the app starts: starting without the right key would create a new one and make every restored provider key unreadable for good.
4. Starts everything again and waits for the app's own health check. The script reports success only once the app is up, and exits with an error otherwise.

When it finishes, open http://localhost:3000/setup. Every card should be green.

Downgrade a version

There is no migration rollback. To return to an earlier version:

1. Restore the backup taken before the update, as above.
2. Pin the older image, for example ghcr.io/nodaroai/nodaro-community:v1.25.1, in NODARO_IMAGE or in docker-compose.community.yml. Exact vX.Y.Z tags never move.
3. Run docker compose -f docker-compose.community.yml up -d nodaro.

See Updating for the tags.

Back up a managed deployment

Outside the compose stack, four things hold state:

If Postgres is down during a migration or a recovery, the API restarts in a loop until it can reach the database. Once Postgres is back, restart the Nodaro container.

Restore into a new Supabase project

A restore into a new Supabase project does not keep the database privileges. A function meant for the server alone can come back callable by the browser roles, anon and authenticated. A table or a column that the migrations closed can come back readable or writable. After any restore, list the SECURITY DEFINER functions that those roles can run:

SELECT p.oid::regprocedure AS function,
       has_function_privilege('anon', p.oid, 'EXECUTE') AS anon,
       has_function_privilege('authenticated', p.oid, 'EXECUTE') AS authenticated
  FROM pg_proc p
 WHERE p.pronamespace = 'public'::regnamespace
   AND p.prosecdef
   AND p.prorettype NOT IN ('trigger'::regtype, 'event_trigger'::regtype)
   AND (has_function_privilege('anon', p.oid, 'EXECUTE')
        OR has_function_privilege('authenticated', p.oid, 'EXECUTE'))
 ORDER BY 1;

The result must hold only the functions listed in browser_callable in the repository's test file supabase/tests/server-only-function-privileges.behavior.sql. Close every other function, and name PUBLIC as well, because anon and authenticated inherit its default EXECUTE:

REVOKE EXECUTE ON FUNCTION public.<name>(<args>) FROM PUBLIC, anon, authenticated;
GRANT EXECUTE ON FUNCTION public.<name>(<args>) TO service_role;

Migration 598 in supabase/migrations/ closes the server-only functions and restores the table and column privileges that the migrations up to it set. It is safe to run again. To check a restored database against the expected privileges, run the test file with psql. It rolls itself back and stops at the first thing that is open:

psql "$DATABASE_URL" -v ON_ERROR_STOP=1 -f supabase/tests/server-only-function-privileges.behavior.sql

Troubleshooting

• the db service is not running. Start the stack first: docker compose -f docker-compose.community.yml up -d.
• Provider keys show missing after a restore. The database was restored without its matching encryption-key, or with a different one. Restore from an archive that has the key, or enter the keys again on /setup.
• Restore verification failed. The script refuses to leave a half-restored database silently. Run the restore again. If it fails repeatedly, the archive may be truncated: compare its size with the original.
• could not read the encryption key during a backup on Windows. You are not in Git Bash, or the app container is not running. Run the backup again from Git Bash with the stack up. The archive the script warned about is not a usable backup.
• media restore verification FAILED or encryption key verification FAILED. The script stopped on purpose and did not start the app. Check the volume it names, fix the cause, usually a stopped container or a full disk, and run the restore again. It is safe to repeat.