Skip to content

Improve restore documentation #73

New issue

Have a question about this project? Sign up for a free GitHub account to open an issue and contact its maintainers and the community.

Sign up for GitHub

By clicking “Sign up for GitHub”, you agree to our terms of service and privacy statement. We’ll occasionally send you account related emails.

Already on GitHub? Sign in to your account

Open
CrossDrain wants to merge 2 commits into
base: docs/backup-restore-clarity
Choose a base branch
from
Open

Improve restore documentation #73

Changes from 1 commit
Commits
Show all changes
2 commits
Select commit Hold shift + click to select a range
2c15e0e
Update self-hosting.mdx to include better explanations or the backup …
CrossDrain May 1, 2026
62c0bd9
Update self-hosting.mdx
CrossDrain May 1, 2026
File filter

Filter by extension

Filter by extension
Conversations
Failed to load comments.
Loading
Jump to
Jump to file
Failed to load files.
Loading
Diff view
Diff view
42 changes: 25 additions & 17 deletions self-hosting.mdx
View file
Open in desktop
Original file line number Diff line number Diff line change
Expand Up @@ -282,26 +282,42 @@ You can use cron syntax or these shortcuts:
- `@monthly` - Once per month
- Custom cron: `0 2 * * *` (2 AM daily)

### Restore from a PostgreSQL backup
### Restore uploaded files

<Warn>
Since the database refernces files (paths, IDs, metadata), file restore should PRECEDE the restore of the database.
</Warn>
Comment thread
CrossDrain marked this conversation as resolved.
Outdated

If your Sure instance stores uploaded files (attachments, profile pictures, etc.) on the local filesystem, restoring the database alone is not enough. You must also restore the files themselves from the corresponding backup.

The exact restore path depends on how you mapped volumes in `compose.yml`. Restore the backup at the same directory that Sure uses for storage. By default, sure will use the `app-storage` Docker volume.
Comment thread
CrossDrain marked this conversation as resolved.
Outdated

If you are using external object storage instead of local disk, restore those files using that provider's backup or versioning workflow instead.

### Restore the database from a PostgreSQL backup

Use this process when you have a SQL dump created by the backup service or with `pg_dump`.

> [!NOTE]
> If you customized the PostgreSQL username, password, or database name in your `.env` or `compose.yml`, replace `sure_user` and `sure_production` in the commands below.
<Danger>
The following process will wipe the current database and will replace it with the backup. All data currently being used by Sure will be lost.
</Danger>

<Note>
If you customized the PostgreSQL username, password, or database name in your `.env` or `compose.yml`, replace `sure_user` and `sure_production` in the commands below.
</Note>

1. Stop the application containers so they do not write to the database during the restore:
1. Stop the application containers so they do not write to the database during the restore.

```bash
docker compose stop web worker
docker compose down
Comment thread
CrossDrain marked this conversation as resolved.
Outdated
```

2. Start or keep the database container running:

2. Start only the Postgres database container
Comment thread
CrossDrain marked this conversation as resolved.
Outdated
```bash
docker compose up -d db
```

3. Locate the backup file in your backup directory, for example `/opt/sure-data/backups`.
3. Locate the backup file in your backup directory, for example in the backup service's `sure-backups` volume.

4. Restore the SQL backup into PostgreSQL:

Expand All @@ -312,17 +328,9 @@ docker compose exec -T db psql -U sure_user -d sure_production < /path/to/backup
5. Restart the app:

```bash
docker compose up -d web worker
docker compose up -d
Comment thread
CrossDrain marked this conversation as resolved.
Outdated
```

### Restore local uploaded files

If your Sure instance stores uploaded files on the local filesystem, restoring the database alone is not enough. You must also restore the app's storage directory from the matching file backup.

The exact host path depends on how you mapped volumes in `compose.yml`. Restore the same directory that Sure uses for local storage, then restart the app containers.

If you are using external object storage instead of local disk, restore those files using that provider's backup or versioning workflow instead.

### Verify the restore

After restoring, check the following:
Expand Down