Skip to main content

How to Update a Discourse Forum

PropertyValue
descriptionHow to Update a Discourse Forum
tagskb
rating

Overview​

This guide documents the normal production-safe process for updating a self-hosted Discourse forum that uses the standard Docker install in /var/discourse.

The key idea is simple:

  • a normal Discourse update is a container rebuild
  • server package updates are separate operating-system maintenance
  • Docker restarts are usually unnecessary unless you are doing separate Docker maintenance

Requirements​

  • SSH access with root or sudo
  • a standard Discourse Docker install in /var/discourse
  • Docker running normally
  • a backup or snapshot strategy before you begin

Verify The Install Path​

SSH into the server and confirm the standard install layout:

cd /var/discourse
ls

You should see the usual files and directories such as:

  • launcher
  • containers/
  • templates/

Back Up Before Updating​

Use at least one of these before rebuilding:

Option 1: Discourse Backup​

cd /var/discourse
./launcher enter app
discourse backup
exit

Option 2: VPS Snapshot​

If your VPS provider supports snapshots, this is the safest rollback point before a rebuild.

Option 3: Filesystem Backup​

cp -r /var/discourse /var/discourse-backup-$(date +%F)

Update Discourse​

For a normal Docker-based Discourse install, the primary update command is:

cd /var/discourse
./launcher rebuild app

That rebuild normally handles:

  • pulling the current app code
  • pulling the current base image
  • running migrations
  • recompiling assets
  • restarting the app services inside the rebuilt container

About git pull​

Older community instructions often include git pull first. That is not the main required step in the current standard Docker workflow. The official update path is centered on rebuilding the container.

If you are following the normal install path, treat this as the core update command:

./launcher rebuild app

Expected Downtime​

Expect a short maintenance window during rebuild, usually around a few minutes.

In practice, this often falls somewhere in the 2 to 15 minute range depending on the server and current update size.

Verify The Update​

After the rebuild finishes:

Check The Container​

docker ps

You should see the Discourse app container running.

Check The Logs​

cd /var/discourse
./launcher logs app

Look for normal startup behavior rather than repeated crash loops.

Check The Site​

Open the forum in the browser and verify:

  • the main site loads
  • admin loads
  • background jobs look normal
  • there are no obvious asset or migration errors

Useful places to verify:

  • /admin
  • /sidekiq

Optional Version Check​

If you want to confirm the running version from inside the container:

cd /var/discourse
./launcher enter app
rails c
Discourse::VERSION::STRING

Then exit the console when finished.

Optional Ubuntu Maintenance​

Operating-system maintenance is separate from the Discourse update itself.

If you also want to update Ubuntu packages:

apt update
apt upgrade -y

needrestart Prompt​

If needrestart appears and you are trying to avoid unnecessary downtime:

  • review the list carefully
  • avoid restarting services blindly
  • be especially careful with SSH and Docker-related services on a remote server

Reboot Only If Needed​

Check whether the system actually requires a reboot:

cat /var/run/reboot-required

If that file exists, schedule a reboot when acceptable.

Docker Restart​

A plain systemctl restart docker is not part of the normal Discourse update process.

It is only relevant if you are doing separate Docker or host maintenance.

If you restart Docker:

  • all containers on that host are affected
  • there will be downtime

For a standard Discourse application update, rebuilding the app container is usually enough.

Troubleshooting​

Rebuild Fails​

Check the logs and rerun the rebuild after understanding the failure:

cd /var/discourse
./launcher logs app
./launcher rebuild app

Container Is Not Running​

Try starting it explicitly:

cd /var/discourse
./launcher start app

Low Disk Space​

Check free space:

df -h

Then clean up old Docker artifacts if needed:

cd /var/discourse
./launcher cleanup

For the normal update path:

ssh root@server
cd /var/discourse

# backup
./launcher enter app
discourse backup
exit

# update discourse
./launcher rebuild app

# verify
docker ps
./launcher logs app

If you also want to do Ubuntu maintenance, do that separately afterwards.

Key Principles​

  • a normal Discourse update is a container rebuild
  • ./launcher rebuild app is the key step
  • Ubuntu package updates are separate from Discourse updates
  • Docker restarts are not part of the standard update flow
  • always back up before rebuilding

Sources​

Official Sources​