Backup and Restore
Staaash is not a backup system. It is a drive. If the disk dies, or you delete the wrong folder, your files are gone unless you have a backup.
What to back up
Section titled “What to back up”Two folders, always together:
libraryholds your uploaded files.postgresholds the database. It remembers file names, folders, people and share links.
A backup with only one of them is not complete. Files without the database lose their names and folders. A database without the files has names that point to nothing.
Keep a copy of your .env file with them. The database only opens with the DB_PASSWORD it was made with, and .env holds that password and your other settings. Store it somewhere safe, because it is a secret.
These are the default names. If you changed UPLOAD_LOCATION or DB_DATA_LOCATION in your .env file, back up those folders instead.
Copy the whole library folder, including its hidden and temporary folders. Unfinished changes keep their safety copies there.
Preview pictures and zip files do not need special care. Staaash can rebuild them. Your original files cannot be rebuilt.
On the Windows server installer, the steps are different. See Windows Server.
Make a backup
Section titled “Make a backup”Stop everything first, so no file changes while you copy.
-
Stop the web app:
docker compose stop staaash -
Give the worker a minute to finish unfinished changes. Then check that none are left:
docker compose exec -T db sh -c 'psql -U "$POSTGRES_USER" -d "$POSTGRES_DB"' <<'SQL'SELECT status, count(*) FROM "StorageMutation"WHERE status IN ('prepared', 'running', 'retrying', 'metadata_committed', 'finalizing')GROUP BY status;SQLRun it again until it prints
(0 rows). A change that says Needs review in admin Storage is not in this list. Leave it as it is, and read Storage Check.On Windows with Docker Desktop, run this in WSL or Git Bash.
-
Stop the worker and the migration step:
docker compose stop worker migrateStaaash 1.x has no migration step. If this says
no such service: migrate, nothing was stopped. Rundocker compose stop workerinstead.Run the check from step 2 once more, because the worker may have started a cleanup job. If it prints any rows, run
docker compose start workerand go back to step 2. -
Stop the database and everything else, including Caddy if you use the HTTPS setup:
docker compose stop -
Check that nothing is running:
docker compose ps --status runningThe list must be empty.
-
Copy both folders (
libraryandpostgres) and your.envfile to your backup place. Copy them in the same session, so they match. -
Start Staaash again:
docker compose up -d
Keep more than one copy. A good start is one copy on another disk in the same house, and one copy somewhere else, such as a different building or an online storage service you trust.
Practice a restore
Section titled “Practice a restore”A backup you never tried is only a hope. Practice on a spare computer, never over your real install.
- Make a new empty folder. Copy in
docker-compose.ymland.envfrom your real install. Do not start anything yet. In the copied.env, setUPLOAD_LOCATION=./libraryandDB_DATA_LOCATION=./postgres, so the practice copy never touches your real files. - Put your backed-up
libraryandpostgresfolders whereUPLOAD_LOCATIONandDB_DATA_LOCATIONpoint. - Start it with
docker compose up -d, and sign in as the owner. - Open admin Jobs and run Restore check. It compares the files on disk with what the database remembers.
- Open a folder, download an old file, upload a small one, and open a share link if you use them.
If something fails, keep the restored copy as it is and do not use it as your main copy. Ask in GitHub Discussions.
Restore for real
Section titled “Restore for real”Do this in your real install’s folder, with the .env that belongs to the backup.
-
Stop everything:
docker compose down -
Rename the current
libraryandpostgresfolders, for example tolibrary.oldandpostgres.old. Do not delete them until the restore works. -
Copy the backed-up
libraryandpostgresfolders to whereUPLOAD_LOCATIONandDB_DATA_LOCATIONpoint. -
If
DB_PASSWORDin.envis not the one from the backup, put the backed-up.envback. -
Start it with
docker compose up -d, sign in as the owner, and run Restore check in admin Jobs. -
When your files look right, you can delete the
.oldfolders.
Backups only work with the version that made them, or a newer one. To go back to an older version, restore a backup made before you updated. See Updating.