Migrating from XenForo to Discourse is a common upgrade path for communities that want a more modern forum platform with real-time updates, powerful moderation tools, and built-in trust levels.

This tutorial explains the complete migration workflow for a self-hosted Discourse deployment, including preparing your XenForo database, installing Discourse, running the importer, and verifying your new forum.

Hosting examples in this guide reference LogicWeb, though the process works the same on any VPS provider that supports Docker and root access.

Migration Overview

A typical XenForo to Discourse migration follows this process.

XenForo Server
→ Export MySQL database and attachments
→ Setup Discourse server
→ Import database using Discourse scripts
→ Validate users, topics, and attachments

The Discourse importer converts the following data automatically:

Users
Forums → Categories
Threads → Topics
Posts
Private messages
Attachments and avatars

Choose a Suitable Hosting Environment

Discourse requires more server resources than XenForo because it runs background jobs, real-time messaging, and search indexing services.

Recommended minimum specifications:

RAM: 2–4 GB
CPU: 2 cores
Storage: 20–50 GB SSD
Operating system: Ubuntu 22.04 LTS

Discourse runs inside Docker containers, which simplifies installation and updates.

If hosting with LogicWeb, a typical configuration might include a 4GB VPS for small communities or an 8GB VPS for medium forums. Larger communities may benefit from a dedicated server, but the most important requirement is root access for Docker.

Shared hosting environments usually will not work for Discourse.

Prepare Your XenForo Forum

Before exporting data, place your forum into maintenance mode to prevent new posts during the migration.

In the XenForo admin panel:

Admin CP → Setup → Options → Board Active

Disable the forum temporarily so the database remains consistent during export.

Export the XenForo Database

Connect to your XenForo server via SSH.

ssh user@your-xenforo-server
Code language: CSS (css)

Export the MySQL database.

mysqldump -u xf_user -p xf_database > xenforo_backup.sql
Code language: CSS (css)

Compress the database file.

gzip xenforo_backup.sql
Code language: CSS (css)

This backup contains all users, threads, posts, and configuration data.

Export Attachments and Media

XenForo attachments are typically stored in these directories:

/data
/internal_data

Create an archive of these folders.

tar -czf xenforo_uploads.tar.gz data internal_data
Code language: CSS (css)

These files include uploaded images, attachments, and avatars.

Transfer Files to Your New Server

Copy the database and attachment archives to your new Discourse server.

scp xenforo_backup.sql.gz root@NEW_SERVER_IP:/var/discourse/shared/standalone/
scp xenforo_uploads.tar.gz root@NEW_SERVER_IP:/var/discourse/shared/standalone/
Code language: JavaScript (javascript)

Once the files are transferred, you can begin installing Discourse.

Install Discourse

Log in to your new server.

ssh root@your-server
Code language: CSS (css)

Update packages and install Docker dependencies.

apt update
apt install git docker.io
Code language: CSS (css)

Clone the Discourse installation repository.

git clone https://github.com/discourse/discourse_docker.git /var/discourse
cd /var/discourse
Code language: PHP (php)

Run the automated installer.

./discourse-setup

The setup script will ask for basic configuration information including the forum hostname, administrator email address, and SMTP mail settings.

After the installer finishes, start the Discourse container.

./launcher start app

At this point, your Discourse instance is installed but still empty.

Import the XenForo Database

Enter the running Discourse container.

cd /var/discourse
./launcher enter app
Code language: JavaScript (javascript)

Install MySQL tools required for the importer.

apt update
apt install mysql-client libmysqlclient-dev

Create a temporary database for the XenForo data.

mysql -u root -p
CREATE DATABASE xenforo_import;
EXIT;
Code language: PHP (php)

Import your backup into the temporary database.

gunzip xenforo_backup.sql.gz
mysql -u root -p xenforo_import < xenforo_backup.sql
Code language: CSS (css)

Configure the XenForo Import Script

Inside the container, navigate to the importer scripts directory.

/var/www/discourse/script/import_scripts
Code language: JavaScript (javascript)

Edit the XenForo importer configuration file.

nano xenforo.rb
Code language: CSS (css)

Update the database connection settings so the importer can access your XenForo data.

XENFORO_DB = "xenforo_import"

@client = Mysql2::Client.new(
  host: "localhost",
  username: "root",
  password: "mysqlpassword",
  database: XENFORO_DB
)
Code language: PHP (php)

Save the file and exit the editor.

Run the Migration Script

Execute the XenForo importer.

RAILS_ENV=production bundle exec ruby script/import_scripts/xenforo.rb

Depending on the size of your forum, the import process may take anywhere from several minutes to several hours.

Typical output will show progress through users, categories, topics, and posts as they are migrated.

Rebuild the Discourse Container

After the importer finishes, rebuild the container to finalize indexing and background jobs.

exit
cd /var/discourse
./launcher rebuild app
Code language: PHP (php)

This step ensures the Discourse search index and caches are updated with your imported data.

Verify the Imported Data

Open your new forum in a web browser.

https://forum.yoursite.com
Code language: JavaScript (javascript)

Check that users, categories, and topics appear correctly.

Verify that user logins work and that avatars were imported successfully.

Review several topics to confirm that attachments and formatting display properly. Private messages should also appear in the Discourse messaging system.

Configure Discourse Settings

After migration, configure important site settings in the Discourse admin panel.

Key settings include email notifications, attachment limits, trust levels, and login requirements for private communities.

Discourse offers extensive moderation tools and automated spam protection through its trust level system.

Configure SEO Redirects

To preserve search rankings and avoid broken links, redirect your old XenForo URLs to the new Discourse URLs.

Example XenForo URL:

/threads/example-topic.123/

Example Discourse URL:

/t/example-topic/456

Nginx rewrite rules can be used to redirect old thread URLs to the corresponding Discourse topics.

Migration Best Practices

Always run a test migration first on a staging server to verify that the importer works correctly with your database.

Remove unused XenForo plugins before exporting the database to reduce potential conflicts.

Expect minor formatting differences since XenForo primarily uses BBCode while Discourse uses Markdown.

Schedule the migration during low traffic hours to minimize disruption for your community.

Final Thoughts

Migrating from XenForo to Discourse can modernize your community platform while preserving years of content and user history.

The overall process involves exporting your XenForo database, installing Discourse on a VPS, running the official importer, and verifying the migrated data.

With proper preparation and testing, most forums can complete the migration with minimal downtime. Hosting the new forum on a properly sized VPS from providers such as LogicWeb ensures the resources required for Discourse’s Docker-based architecture and background services.