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. Backups that include uploads are saved as .tar.gz files, while backups without uploads are saved as .sql.gz files. 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 with a checkbox to include the site’s uploads in the backup. Check or uncheck this option based on your preference.

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. Click the confirmation button to start the backup.

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, navigate to the Backup Files tab, 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, on the Backups page, find the backup you want to restore, click the more options menu (⋮), and select 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 option 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]

백업 파일을 다운로드하는 데 어려움을 겪고 있습니다. 다운로드 버튼을 클릭했을 때, 내 이메일 주소로 다운로드 링크가 전송되었다는 안내 메시지가 표시되었습니다. 하지만 이틀이 지났는데도 아직 이메일을 받지 못했습니다.

부디 도움을 부탁드립니다.

[Ethsim2 (Ethan)]

./discourse-doctor를 실행해 보셨나요?

[Athenkosi]

답변해 주셔서 감사합니다. 문제는 백엔드에서 관리자로 다른 이메일을 설정해 놓은 상태인데, 포트 587에 대한 연결이 계속 실패하고 이메일이 전송되지 않습니다. 이 문제를 우회할 수 있는 방법이 있거나, 사용할 수 있는 다른 포트가 있을까요?

[Ethsim2 (Ethan)]

이것이 설정한 이메일 주소의 대체 응답인가요?

[Ethsim2 (Ethan)]

포트 587은 smtp.eu.mailgun.org에 연결할 때 사용하는 포트입니다.

메일건(Mailgun)에 지원 티켓을 등록하여 승인을 받은 후 사용해야 합니다.

[Athenkosi]

서버 설정에 현재 이렇게 되어 있습니다.

[Ethsim2 (Ethan)]

아, 그러시군요. 루트 도메인에 Office 365를 설정하고

서브 도메인에서는 CNAME&TXT로 Discourse 트랜잭션 이메일을, MX로 메일 수신 기능을 설정하려는 것이죠?

[Athenkosi]

네, 제 이메일이 365로 설정되어 있기 때문입니다.

[NateDhaliwal]

문제의 원인은 트랜잭션 이메일을 위해 Office 365를 사용하고 있기 때문이라고 생각합니다. Mailgun이나 Brevo와 같은 트랜잭션 메일 서비스를 사용하는 것이 좋습니다. 이 두 서비스 모두 Discourse와 함께 큰 문제 없이 사용할 수 있습니다.

[Ethsim2 (Ethan)]

설명된 설정 구성에 도움을 드릴 수 있습니다. 현재 Office 365 구독을 사용하여 Discourse 이메일을 보내거나 받을 수 없습니다.

어떤 규모의 포럼을 구상하고 계신가요? 무료(discourse/transactional) 이메일 플랜으로도 충분할 수 있습니다.

[Athenkosi]

Brevo를 사용하여 SMTP 설정을 구성하고 포트 587을 사용했는데도 여전히 동일한 오류가 발생합니다. 어디서 잘못되고 있는지 모르겠으니 도움을 주실 수 있을까요?

[NateDhaliwal]

음… 포트를 2525로 변경하는 건 어떨까요?

[Ethsim2 (Ethan)]

이것이 제대로 작동하는지 확인해 보셨나요?

[xu2]

백업 파일을 업로드할 때, 다운로드한 백업 파일을 선택할 수 없습니다. 파일이 회색으로 표시되어 선택이 불가능합니다. 파일은 tar.gz 확장자를 가지고 있습니다.

[pfaffman (Jay Pfaffman)]

복원하려는 업로드된 파일이 최근 버전의 Discourse 노트인가요?

[tobiaseigen]

@xu2

해당 파일의 확장자가 .tar.gz입니다.

파일 이름을 변경해 보셨나요? 백업 생성 시 지정된 이름이 아니면 작동하지 않습니다.