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.

Read-only mode

You can enable read-only mode on the Backups page to prevent site changes for admin-related tasks. Learn more about read-only mode here.

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 @hugh 2025-10-03T04:56:55Z

Last checked by @hugh 2025-10-03T04:57:04Z

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]

Het lukt me niet om een back-up te downloaden. Toen ik op de downloadknop klikte, kreeg ik een melding dat er een downloadlink naar mijn e-mailadres was gestuurd. Het is echter al meer dan twee dagen geleden en ik heb de e-mail nog steeds niet ontvangen.

Kunt u alstublieft helpen.

[Ethsim2 (Ethan)]

Heb je ./discourse-doctor al geprobeerd

[Athenkosi]

Bedankt voor uw reactie. Het belangrijkste probleem is dat ik een andere e-mail van de backend als beheerder heb geconfigureerd. De verbinding met poortnummer 587 blijft mislukken en e-mails worden niet verzonden. Is er een manier om dit te omzeilen, of is er een andere poort die ik kan gebruiken?

[Ethsim2 (Ethan)]

is dit het alternatieve antwoord per e-mailadres dat u hebt geconfigureerd?

[Ethsim2 (Ethan)]

poort 587 gebruik ik om verbinding te maken met smtp.eu.mailgun.org

na het inloggen van een supportticket bij mail-gun om goedkeuring te krijgen

[Athenkosi]

This is what I have on my server settings.

[Ethsim2 (Ethan)]

Oké, dus je wilt Office 365 op je hoofddomein

en Discourse transactionele e-mail via CNAME&TXT / mail-receiver via MX op een subdomein?

[Athenkosi]

Ja, want mijn e-mail is ingesteld op 365

[NateDhaliwal]

Ik denk dat de oorzaak van het probleem is dat je Office 365 gebruikt voor transactionele e-mails. Je zou een transactionele e-maildienst zoals Mailgun of Brevo kunnen gebruiken, die beide zonder veel problemen met Discourse worden gebruikt.

[Ethsim2 (Ethan)]

Ik kan u helpen met de beschreven installaties. Op dit moment kunt u geen e-mails van Discourse verzenden of ontvangen met uw Office 365-abonnement(en).

Op welke schaal van forum kijken we hier? Een gratis (Discourse/transactioneel) e-mailplan is mogelijk voldoende.

[Athenkosi]

Ik heb de SMTP-instellingen geconfigureerd met Brevo en poort 587 gebruikt, en ik krijg nog steeds dezelfde foutmelding. Kunt u mij alstublieft helpen, ik weet niet waar ik de fout maak.

[NateDhaliwal]

Hmm… wat dacht je ervan om de poort te veranderen naar 2525?

[Ethsim2 (Ethan)]

were you able to get this working?