I'm writing a short documentation for admins of Discourse forums I've helped set up. Do I miss something in it?

Canapin · December 27, 2025, 5:47pm

I’ve set up Discourse forums for several friends/associations. I’d like them to be more autonomous when administering, so I’ll be less likely to intervene myself.

They have been using Discourse as users and co-admins for months or years. They are not “new admins”, but they lack in-depth knowledge on how to maintain Discourse on a daily basis (outside moderation basics) and what should be known, as an admin, and in case of technical troubles, because I was always here to take care of such things.

I’ll still be available in the future, but the goal is to allow them track and address the most common issues by themselves.

Here’s what I wrote so far (IA-translated to English because my text will be written in French, so don’t pay attention if some sentences are weirdly written):

Updates

Via the web interface

Run updates when there is an unhappy red smiley in the admin panel (it means there is an important update to apply).
Updates are done via:
https://tonforum.fr/admin/upgrade

They are sometimes done in two steps: you must first update “Docker_Manager” before you can upgrade the rest:

Via the command line

Sometimes, an update must be done via the command line (the Discourse admin page will explicitly say so if needed).

Connect to the server via SSH
Rebuild the forum (a rebuild always updates Discourse) using the following command:
```
/var/discourse/launcher rebuild app
```
From time to time, once you have confirmed that the forum is working correctly, it can be useful to remove unused Docker images (leftovers from previous upgrades) to free up disk space:
```
/var/discourse/launcher cleanup
```

Location of important files on the server

`app.yml`

Contains the server configuration and the list of installed plugins. Very useful if you need to migrate the forum to another server or apply certain configurations (for example, moving uploads and backups to another disk). It is located here:

/var/discourse/containers/app.yml

`mail-receiver.yml`

Contains the configuration for the software that allows receiving replies by email and publishing them on the forum. It is located here:

/var/discourse/containers/mail-receiver.yml

Backups

Backup files are stored here:

/var/discourse/shared/standalone/backups/default

Important pages in the forum admin

Some pages that can be useful

Themes and components

They include custom CSS and HTML:

https://tonforum.fr/admin/config/customize/themes

Logs

Email

Useful for debugging:

https://tonforum.fr/admin/email-logs

Staff actions

Very useful. It keeps a record of (almost) all site setting changes and other actions performed by moderators and admins.

https://tonforum.fr/admin/logs/staff_action_logs

Error logs

Can provide clues when a problem is not obvious:

https://tonforum.fr/logs/

Backups

To change the backup frequency and maximum number of backups, view them, or download them:

https://tonforum.fr/admin/backups

Resources

https://meta.discourse.org
Official support. Do not hesitate to post there; community members and developers are usually very helpful.

Do you see some things that could be added/removed? I think I can remove the /logs/ part, as it is very, very rarely useful. I’m not even sure I found useful information in it in many years of administering a few instances.

Ed_S · December 27, 2025, 9:42pm

A couple of things I’d want to make clear.

One is, at the point of trying an update by web interface, be aware that the update may fail, and your forum may be down. Be prepared.

Another is, if your host becomes inaccessible or corrupted, you will need the backup files and the yml files. You will need to have them already somewhere safe on a separate system.

To combine the two: always take a backup, and download the backup, before trying an update.

Heliosurge · December 27, 2025, 10:58pm

Hi Ed very valid points. A member awhile back did create a script for backing up to another system as I recall. Will need to do a search and check

Here is quite if the Op post. Canapin has a good reply with a link to backing up to Google drive)Dropbox as well

Powershell script for sysadmin to regularly download backups from server to computer

Recently, a friend of mine encountered the problem of the VPS provider suddenly going out of business without notice. Unfortunately, for the sake of cheap, she chose a niche provider - one that didn’t even offer any data downloads. What’s worse is that she doesn’t even have the habit of downloading backups regularly. Overnight, her site disappeared, along with all the data on it.

Shocked by this, I wrote a Powershell script that will automatically download backups from your server to your local computer regularly without having to purchase any additional object storage services or spend a penny on other things. All you need is a Windows computer that you use regularly (and has plenty of hard drive space) and is connected to the Internet.

The script will automatically clean up backups from 5 days ago. You can set the automatic backup interval and the oldest backup time saved locally according to your needs.
$ssh_port = 22
$ssh_address = "username@your.site"


Write-Output "Starting Discourse backup download task..."
Write-Output '------------------------'
Write-Output "Fetching the latest backup file..."
Write-Output ''

while ($true) {

    $filename = ''

    while ($true) {
        try {
            Write-Output "> ssh -p $ssh_port $ssh_address 'cd /var/discourse/shared/standalone/backups/default/ && ls -t | head -n 1'"
            Write-Output ''
            $filename = ssh -p $ssh_port "$ssh_address" 'cd /var/discourse/shared/standalone/backups/default/ && ls -t | head -n 1'
            break
        }
        catch {
            $filename = ''
    
            Write-Output "Failed to fetch... Here is the log:"
            Write-Output '-------------'
            Write-Output $_
            
            $answer = Read-Host "Do you want to re-fetch? (y/N)"
            if ($answer -ne 'y') {
                break
            }
            Write-Output ''
        }
    }
    
    
    if ([String]::IsNullOrEmpty($filename)) {
        Write-Output "Error: Failed to fetch file name $filename"
        Write-Output ''
        $answer = Read-Host 'Retry?(y/N)'
  
        if ($answer -eq 'y') {
  
        }
        else {
      
            exit 1
        }
  
    }
    else {

        Write-Output "Latest backup: $filename"
        Write-Output ''
        
        $need_download = $true
        if (Test-Path ".\backups\$filename") {
            $answer = Read-Host ".\backups\$filename already exists. Do you want to download it again?(y/N)"
            Write-Output ''
            if ($answer -ne 'y') {
                $need_download = $false
            }
        }
        if ($need_download) {
            Write-Output "Start downloading..."
            Write-Output ''
            
            while ($true) {
                try {
                    Write-Output "scp -p $ssh_port ${ssh_address}:/var/discourse/shared/standalone/backups/default/$filename .\backups\"
                    Write-Output ''

                    scp -p $ssh_port "${ssh_address}:/var/discourse/shared/standalone/backups/default/$filename" .\backups\
                    
                    Write-Output "Download completed"
                    Write-Output ''
                    
                    break
                }
                catch {

                    Write-Output "Download failed >_<... The following is the log:"
                    Write-Output ''

                    Write-Output $_
                    
                    $answer = Read-Host "Download again? (y/N)"
                    Write-Output ''
                    if ($answer -ne 'y') {
                        break
                    }
                }
            }

        }
  
        Write-Output "Start trying to clean old backup files..."
        Write-Output ''

        $count = 0
        $backupfiles = Get-ChildItem -Path .\backups\
  
        foreach ($file in $backupfiles) {
            if ($file.CreationTime -le (Get-Date).AddDays(-5)) {
                try {
                    Write-Output "Delete old backup file $file ..."
                    Write-Output ''
                    $file.Delete()
                    $count = $count + 1
                } catch {
                    Write-Output "An error occurred while deleting old backup file $file >_<"
                    Write-Output '-------------------'
                    Write-Output $_
                    Write-Output '-------------------'
                }
            }
        }

        if ($count -ge 0) {
            Write-Output "Cleaned $count old backup files"
            Write-Output ''
        }
        else {
            Write-Output 'No old backup files need to clean up'
            Write-Output ''
        }

        Pause
  
        exit 0
  
    }
  
  
}
Save the above script as scriptname.ps1 in the path where you wish to download the backup. Try “Run with Powershell”. If successful, then you can proceed to the next step.

To schedule a task

Search “Scheduled Tasks”.

Double-click Add Scheduled Task. The Scheduled Task Wizard appears.

Click Next, then click Browse. The Select Program to Schedule dialog appears.

Navigate to the script that you created click it, then Open. You are returned to the Scheduled Task Wizard.

Provide a name for the task, or keep the default, which is the filename, specify how often to run the script, then click Next.

Specify the starting time and date (if you specified Daily, Weekly, or Monthly, or etc.) and recurrence, then click Next. This item should match the automatic backup cycle of your discourse

Type the user name and password for the account that will run the script, then click Next.

If you want to configure advanced properties, select the check box, then click Finish.

@Canapin with the launcher rebuild app, doesn’t it need to be ran as

./launcher r build app

This is just how U have been used to running it from other doc’s here in the site. As I have learned though there is often many ways to di things. Lol

Nice write up handy

NateDhaliwal · December 28, 2025, 12:56am

But since you would cd /var/discourse before that, ./ would just refer to that directory, so launcher’s path is essentially /var/discourse/launcher, no?

Heliosurge · December 28, 2025, 3:58am

I wasn’t aware if that. I have just been using it as per other tutorials on discourse. But makes sense. Thank you

Ed_S · December 28, 2025, 6:01am

I wonder if it’s worth adding some escalation tips? If the person reading the document doesn’t know how to ssh into the host, to investigate or fix, who can? Perhaps a tip about asking questions here on meta, perhaps also a tip about using ask.

Jonathan5 · December 28, 2025, 11:42pm

That’s good to know. I only knew about downloading the backup created by the forum itself.

Canapin · December 29, 2025, 2:09pm

Thank you for your help!

I’ve added this at the beginning of my guide:

Make sure you’re prepared for any situation

It is strongly recommended, in addition to local backups (saved on the same server as the forum), to have a copy of these backups on another server or in the cloud^[1].

It is also useful to keep a copy of the file /var/discourse/containers/app.yml in a secure place^[2]. This optional file is used in case of a forum reinstallation or a migration to another server.

If there is any serious doubt about anything, contact me (canapin@gmail.com).

Added this in the update section:

Before doing an update, it is strongly recommended to download the latest backup of your forum.

Added this:

What to do if the forum no longer works?

Rebuilding the forum fixes many problems and is done with the same command as a command-line update:
/var/discourse/launcher rebuild app
What if the forum still doesn’t work after a rebuild?

Ask me (canapin@gmail.com) or post on the official support forum.

I also mentioned ask.discourse.org at the end of the guide.

Resources

https://meta.discourse.org : official support, don’t hesitate to post there — community members and devs are very helpful
https://ask.discourse.com : a chatbot trained on Discourse support and data, surprisingly effective for answering questions (yes, really)

Full text

Make sure you’re prepared for any situation

It is strongly recommended, in addition to local backups (saved on the same server as the forum), to have a copy of these backups on another server or in the cloud^[1:1].

It is also useful to keep a copy of the file /var/discourse/containers/app.yml in a secure place^[2:1]. This optional file is used in case of a forum reinstallation or a migration to another server.

If there is any serious doubt about anything, contact me (canapin@gmail.com).

Updates

Before doing an update, it is strongly recommended to download the latest backup of your forum.

Via the interface

Do updates when there is an unhappy red smiley in the admin (it means there is an important update to do).
Updates are done via https://yourforum.com/admin/upgrade

They are sometimes done in two steps: you first need to update “Docker_Manager” before being able to upgrade the rest:

Via the command line

Sometimes, an update must be done via the command line (the Discourse admin page will say so if needed).

Connect to the server via SSH
Rebuild the forum (a rebuild always updates Discourse) using the following command:
```
/var/discourse/launcher rebuild app
```
From time to time, after making sure the forum works correctly, it can be useful to remove unused Docker images (leftovers from previous upgrades) to free disk space:
```
/var/discourse/launcher cleanup
```

What to do if the forum no longer works?

Rebuilding the forum fixes many problems and is done with the same command as a command-line update:

/var/discourse/launcher rebuild app

I think it’s quite good now and that I don’t miss anything important

If I installed your forum, your backups are automatically copied to my Google Drive, but ideally in the future they should be saved on a space you are responsible for. We’ll talk about it one day ↩︎ ↩︎
It contains the mail server username and password as well as the top-level administrator email (mine, actually). ↩︎ ↩︎

Jonathan5 · December 29, 2025, 6:52pm

If this works then it would be a better (simpler) recommendation than the usual two-line version (which used to be three, so we can continue the trend).

merefield · December 29, 2025, 7:16pm

Both work.

If you are in the directory ./ Is required because launcher location is not in path.

Linux requires that if a command is not in path you give it’s full path so there can be no mistake which file you meant.

merefield · December 29, 2025, 7:19pm

Yes but often you might be doing multiple things e.g. a cleanup first. In which case cd-ing first might end up more brief.

Andrew_Rowe · December 30, 2025, 2:27am

I agree and I have bookmarked the topic for future use, thanks

Canapin · December 30, 2025, 4:17pm

Oh well, here’s the full automatically translated guide then:

Making sure you’re prepared for any eventuality

It is strongly recommended, in addition to local backups (stored on the same server as the forum), to have a copy of those backups on another server or in the cloud^[1].

It is also useful to keep a copy of the file /var/discourse/containers/app.yml in a secure location^[2]. This optional file is useful in case of a forum reinstallation or migration to another server.

~~If you have any serious doubts about anything, contact me.~~

Updates

Before doing an update, it is strongly recommended to download the latest backup of your forum.

Via the interface

Do updates when there is an unhappy red smiley in the admin (it means there is an important update to do).
Updates are done via https://tonforum.fr/admin/upgrade

They sometimes happen in two steps: you first need to update “Docker_Manager” before being able to upgrade the rest:

Via the command line

Sometimes an update has to be done via the command line (the Discourse admin page will say so if it’s necessary).

Connect to the server via SSH
Rebuild the forum (a rebuild always updates Discourse) using the following command:
```
/var/discourse/launcher rebuild app
```
From time to time, after making sure the forum works correctly, it can be useful to remove unused Docker images (leftovers from previous upgrades) to free up disk space:
```
/var/discourse/launcher cleanup
```

What to do if the forum no longer works?

Rebuilding the forum fixes many problems and is done with the same command as an update via the command line:

/var/discourse/launcher rebuild app

What if the forum still doesn’t work after a rebuild?

~~Ask me or~~ post on the official support forum.

Location of important files on the server

`app.yml`

It contains the server configuration and the list of installed plugins. Very useful if the forum needs to be moved to another server, or for certain configurations (moving uploads and backups to another disk, for example). It is located here:

/var/discourse/containers/app.yml

`mail-receiver.yml`

It contains the configuration of the software that allows replies by email to be received and published on the forum. It is located here:

/var/discourse/containers/mail-receiver.yml

Backups

Backup files are located here:

/var/discourse/shared/standalone/backups/default

Important pages in the forum admin:

Pages that can be useful

Themes and components

They contain, among other things, custom CSS and HTML:

https://tonforum.fr/admin/config/customize/themes

Logs

Email

Useful for debugging:

https://tonforum.fr/admin/email-logs

Staff actions

Very useful. It keeps a record of (almost) all site setting changes and other moderator and admin actions.

https://tonforum.fr/admin/logs/staff_action_logs

Error logs

Can give clues when there is a problem whose cause isn’t obvious.

https://tonforum.fr/logs/

Backups

To change backup frequency and maximum number, view them, or download them:

https://tonforum.fr/admin/backups

Resources

https://meta.discourse.org : official support, don’t hesitate to post there, members and devs are happy to help
https://ask.discourse.com : a chatbot trained on Discourse support and data, surprisingly effective at answering questions (yes, really)

~~If I installed your forum, your backups are automatically copied to my Google Drive, but ideally in the future they should be saved to a space you are responsible for. We’ll talk about it someday~~ ↩︎
It contains the identifier and password for the mail server, as well as the administrator email ~~(mine, actually)~~. ↩︎

Topic		Replies	Views
MKJ's Opinionated Discourse Deployment Configuration Sysadmins explanation , install	32	6730	December 15, 2025
Problem when updating Discourse Forum Installation unsupported-install	20	2007	June 29, 2023
Digital Ocean hosting: Do I need a system admin? Hosting	28	6695	December 14, 2017
How to backup and restore a whole /var/discourse app folder? Installation	17	5552	June 19, 2020
Improving import and export support Feature	29	8432	October 8, 2014

I'm writing a short documentation for admins of Discourse forums I've helped set up. Do I miss something in it?

Updates

Via the web interface

Via the command line

Location of important files on the server

app.yml

mail-receiver.yml

Backups

Important pages in the forum admin

Themes and components

Logs

Email

Staff actions

Error logs

Backups

Resources

Make sure you’re prepared for any situation

What to do if the forum no longer works?

What if the forum still doesn’t work after a rebuild?

Resources

Make sure you’re prepared for any situation

Updates

Via the interface

Via the command line

What to do if the forum no longer works?

Making sure you’re prepared for any eventuality

Updates

Via the interface

Via the command line

What to do if the forum no longer works?

What if the forum still doesn’t work after a rebuild?

Location of important files on the server

app.yml

mail-receiver.yml

Backups

Important pages in the forum admin:

Themes and components

Logs

Email

Staff actions

Error logs

Backups

Resources

Related topics

`app.yml`

`mail-receiver.yml`

`app.yml`

`mail-receiver.yml`