Create, download, and restore a backup of your Discourse database

[Discourse]

This guide provides step-by-step instructions for creating, downloading, and restoring a backup of your Discourse database.

Required user level: Administrator

Discourse allows site administrators to create and download a copy of the site’s database. The backup can then be uploaded and restored to any Discourse forum.

Discourse backups include the full site database, which contains everything on the site: topics, posts, users, groups, settings, themes, etc. Depending on how the backup file is created, it may or may not include uploads. See the next section for details.

Though the data created by plugins exist in the database, the plugins themselves are installed in your app.yml file. To restore your site to a new server you will need to make sure that your installation includes the plugins you require.

Create a backup

To create a backup of your Discourse site, follow these steps:

1. Go to the Admin / Backups section of your site.
2. Click the Backup button.

3. A modal window will open asking you whether or not you would like to include the site’s uploads in the backup. Specify whether you want to include site uploads in your backup.

If your site is hosted by us and you would like to create a backup that includes uploads, contact the Discourse team before creating the backup.

4. Initiate the backup by selecting your preferred option.

Download a backup

When the backup is complete, Discourse will send you a notification.

• Click the link in the notification to return to your Backups page. Then click the Download button.

• An email with a link to download the backup will be sent to you. Click the link to save the backup to your computer.

Upload a backup

• To upload a backup, go to the Admin / Backups section of your site and click the Upload button.

• This will open your browser’s file manager. Select the backup from your file system and click the file manager’s Open button. The new backup file will be displayed in the file list.

Restore a backup

Before you are able to restore your backup file you need to enable the allow restore site setting. Then click the Restore button on the Backups page for the backup you want to restore.

Restoring a backup file will overwrite all data on the site. When the backup is restored, you will be logged out of the site and need to log back in with your credentials from the restored site.

Make sure the site you are restoring into is running the same version of Discourse as the old site. It is best to update both sites to the latest version before running the backup/restore process.

The restore process automatically sets the disable emails setting to “non-staff”, so emails aren’t sent to your site’s users until you’re ready.

If your site is hosted by Discourse, the Restore button in the screenshot below will be disabled. After uploading the backup file, contact the Discourse team and let us know the name of the backup file that you wish to restore. We will restore it for you.

Command line backup and restore

For administrators comfortable with the command line, you can create and manage backups programmatically:

• Backups are stored in /var/discourse/shared/standalone/backups.
• Start a backup using:

./launcher run app discourse backup

or

docker exec app bash -c "discourse backup"

For more information about command line backups, see: Backup discourse from the command line.

Last edited by @SaraDev 2024-08-23T20:11:51Z

Check document

Perform check on document:

[lega4]

Is there a way to create and download this backup file programmatically? I mean, I have some cron scripts on the server which do backups for tons of other services, can I issue a few CLI commands directly on the server to get the backup there? Maybe ./launcher app backup new-backup.backup or so?

[pfaffman (Jay Pfaffman)]

The backups are in /var/discourse/shared/standalone/backups

You can start a backup with

./launcher run app discourse backup

Or

docker exec app bash -c "discourse backup" 

I think.

[das-g (Raphael Das Gupta)]

Is this also possible in a Docker development environment, set up as outlined at Install Discourse for development using Docker?

When I try it as described in the section Create a backup above, I get the error pg_dump: error: connection to database "discourse_development" failed: connection to server on socket "/var/run/postgresql/.s.PGSQL.5432" failed: FATAL: Peer authentication failed for user "postgres".

Full log of the failed backup

[2024-09-04 15:03:39] [STARTED]
[2024-09-04 15:03:39] 'raphael.dasgupta' has started the backup!
[2024-09-04 15:03:39] Marking backup as running...
[2024-09-04 15:03:39] Making sure '/src/tmp/backups/default/2024-09-04-150339' exists...
[2024-09-04 15:03:39] Making sure '/src/public/backups/default' exists...
[2024-09-04 15:03:39] Updating metadata...
[2024-09-04 15:03:39] Dumping the public schema of the database...
[2024-09-04 15:03:40] pg_dump: error: connection to database "discourse_development" failed: connection to server on socket "/var/run/postgresql/.s.PGSQL.5432" failed: FATAL:  Peer authentication failed for user "postgres"
[2024-09-04 15:03:40] EXCEPTION: pg_dump failed
[2024-09-04 15:03:40] /src/lib/backup_restore/backuper.rb:173:in `dump_public_schema'
/src/lib/backup_restore/backuper.rb:36:in `run'
/src/script/spawn_backup_restore.rb:9:in `backup'
/src/script/spawn_backup_restore.rb:31:in `block in <main>'
/src/script/spawn_backup_restore.rb:4:in `fork'
/src/script/spawn_backup_restore.rb:4:in `<main>'
[2024-09-04 15:03:40] Cleaning stuff up...
[2024-09-04 15:03:40] Removing '.tar' leftovers...
[2024-09-04 15:03:40] Marking backup as finished...
[2024-09-04 15:03:40] Notifying 'raphael.dasgupta' of the end of the backup...

[Athenkosi]

I’m struggling to download a backup. When I clicked the download button, I received a prompt saying a download link had been sent to my email address. However, it’s been over two days now and I still haven’t received the email.

Please kindly assist.

[Ethsim2 (Ethan)]

have you tried ./discourse-doctor

[Athenkosi]

Thanks for your response. The main issue is I have configured another email from the backend as admin. Connection to port number 587 keeps failing, and emails are not sending. Is there a way around it, or is there another port to use?

[Ethsim2 (Ethan)]

is this the alternative reply by email address that you have configured?

[Ethsim2 (Ethan)]

port 587 is what i use to connect to smtp.eu.mailgun.org

after logging support ticket with mail-gun to get approval

[Athenkosi]

This is what I have on my server settings.

[Ethsim2 (Ethan)]

i see, so you want office 365 on your root domain

and Discourse transactional email by CNAME&TXT / mail-receiver by MX on a sub-domain ?

[Athenkosi]

Yes, because my email is set on 365

[NateDhaliwal]

I think the cause of the problem is because you’re using Office 365 for transactional emails. You may want to use a transaction mail service like Mailgun or Brevo, both used with Discourse without much problem.

[Ethsim2 (Ethan)]

i can help you with the setups’ described. At present, you will not be able to send or receive Discourse emails using your Office 365 subscription(s).

What scale of forum are we looking at here? a free (discourse/transactional) email plan may suffice