Skip to content
Try the demo

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.

Two folders, always together:

  • library holds your uploaded files.
  • postgres holds 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.

Stop everything first, so no file changes while you copy.

  1. Stop the web app:

    docker compose stop staaash
  2. 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;
    SQL

    Run 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.

  3. Stop the worker and the migration step:

    docker compose stop worker migrate

    Staaash 1.x has no migration step. If this says no such service: migrate, nothing was stopped. Run docker compose stop worker instead.

    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 worker and go back to step 2.

  4. Stop the database and everything else, including Caddy if you use the HTTPS setup:

    docker compose stop
  5. Check that nothing is running:

    docker compose ps --status running

    The list must be empty.

  6. Copy both folders (library and postgres) and your .env file to your backup place. Copy them in the same session, so they match.

  7. 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.

A backup you never tried is only a hope. Practice on a spare computer, never over your real install.

  1. Make a new empty folder. Copy in docker-compose.yml and .env from your real install. Do not start anything yet. In the copied .env, set UPLOAD_LOCATION=./library and DB_DATA_LOCATION=./postgres, so the practice copy never touches your real files.
  2. Put your backed-up library and postgres folders where UPLOAD_LOCATION and DB_DATA_LOCATION point.
  3. Start it with docker compose up -d, and sign in as the owner.
  4. Open admin Jobs and run Restore check. It compares the files on disk with what the database remembers.
  5. 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.

Do this in your real install’s folder, with the .env that belongs to the backup.

  1. Stop everything:

    docker compose down
  2. Rename the current library and postgres folders, for example to library.old and postgres.old. Do not delete them until the restore works.

  3. Copy the backed-up library and postgres folders to where UPLOAD_LOCATION and DB_DATA_LOCATION point.

  4. If DB_PASSWORD in .env is not the one from the backup, put the backed-up .env back.

  5. Start it with docker compose up -d, sign in as the owner, and run Restore check in admin Jobs.

  6. When your files look right, you can delete the .old folders.

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.