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 all commits
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
45 changes: 24 additions & 21 deletions self-hosting.mdx
View file
Open in desktop
Original file line number Diff line number Diff line change
Expand Up @@ -282,47 +282,50 @@ 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

Use this process when you have a SQL dump created by the backup service or with `pg_dump`.
<Warning>
Since the database refernces files (paths, IDs, metadata), file restore should PRECEDE the restore of the database.
</Warning>

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

1. Stop the application containers so they do not write to the database during the restore:
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.

```bash
docker compose stop web worker
```
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`.

2. Start or keep the database container running:
<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. While the stack is running, stop the application containers so they do not write to the database during the restore:

```bash
docker compose up -d db
docker compose stop web worker
```

3. Locate the backup file in your backup directory, for example `/opt/sure-data/backups`.
2. 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:
3. Restore the SQL backup into PostgreSQL:

```bash
docker compose exec -T db psql -U sure_user -d sure_production < /path/to/backup.sql
```

5. Restart the app:
4. Restart the rest of the containers:

```bash
docker compose up -d web worker
```

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