Discourse is a containerized application that’s relatively straightforward to install, but on mainland Chinese servers, the installation can get stuck or fail for various reasons. This topic will walk you through successfully installing Discourse on both mainland Chinese and overseas servers.
Minimum Server Requirements
CPU: 2 cores
Memory: 4G
Available storage: 10G+
Once your server is ready, you can begin the installation.
Install Docker
First, you’ll need to install Docker on your system. You can follow the official Docker installation guide, which supports installation on nearly all major operating systems. This tutorial uses AlmaLinux 9 for demonstration.
For mainland Chinese servers, use the Tsinghua University mirror to speed up downloads. Instructions are available at:
Once Docker is installed, run systemctl enable --now docker to set it to start on boot and launch the Docker service immediately.
For mainland Chinese servers, configure Docker mirror acceleration. Edit the file /etc/docker/daemon.json using vim and paste the following content:
{
"registry-mirrors": [
"https://docker.1ms.run"
]
}
Save the file, then run systemctl restart docker to restart the Docker service.
Prepare Discourse Installation Environment
- A functional SMTP email account for sending administrator activation emails.
- A forum domain name pointed to your server’s public IP address, which you will need to enter during the installation process.
- Git installed on your server, using either
dnf install gitorapt install git.
Once your environment is fully prepared, you can download the Discourse Docker management tool.
sudo -s
git clone https://github.com/discourse/discourse_docker.git /var/discourse
cd /var/discourse
chmod 700 containers
If you are unable to connect to GitHub from a mainland Chinese server, you can search for available GitHub acceleration proxy services or set up your own.
Once everything is set up correctly, you can proceed to install Discourse.
Install Discourse
Run ./discourse-setup to launch the installation wizard.
You will be prompted to enter your forum’s domain name; enter it and press Enter. The wizard will then check your domain’s DNS resolution. If the check fails, you will not be able to proceed further.
If the prompt indicates that your domain is not properly resolved, you can manually adjust the configuration to continue the installation, though this method is outside the scope of this guide. Once you have resolved the DNS issue, re-run ./discourse-setup to launch the installation wizard again.
Next, you will be asked to enter your administrator email address, SMTP server, SMTP port, SMTP username, SMTP password, notification email address, as well as the optional Let’s Encrypt notification email address and Maxmind license key. Fill out all required fields as prompted.
Finally, a confirmation screen will appear; press Enter if all details are correct to begin the installation.
For overseas servers, simply wait for the installation to complete. For mainland Chinese servers, press Ctrl+C to terminate the installation wizard and proceed with the following steps.
Modifications for Mainland Chinese Servers
For well-documented reasons, you will need to modify your configuration files to successfully install Discourse on mainland Chinese servers. Without these modifications, the installation will likely get stuck at some step or fail entirely.
Open the main configuration file with vim containers/app.yml, and add - "templates/web.china.template.yml" after - "templates/web.template.yml" in the templates section.
Once you have made these changes, save and close the file, then run ./launcher rebuild app to begin the installation. (After applying these optimizations, you can directly enter the GitHub link for plugins in the plugin configuration section, without needing to convert it to a mirror link.)
Post-Installation Steps
Open your forum’s domain name in a web browser to configure your website settings and create your administrator account.
Activate your administrator account via email and log in to the admin dashboard. The installation is now complete! Congratulations on setting up your own Discourse forum.
