As a containerized software, Discourse is relatively simple to install. However, on servers located in mainland China, installation may get stuck or even fail for various reasons. This topic will explain how to smoothly install Discourse on both servers in mainland China and servers outside mainland China.
Recommended Minimum Server Specifications
CPU: 2 cores
RAM: 4 GB
Available storage: 10 GB+
Once your server is ready, you can begin the installation.
Install Docker
First, you need to install Docker on your system. You can refer to Docker’s official installation tutorial, which supports installation on almost all mainstream operating systems. This guide uses AlmaLinux 9 for demonstration.
For servers in mainland China, use the Tsinghua University mirror for accelerated installation. Instructions are available here:
After Docker is installed, run systemctl enable --now docker to enable auto-start on boot and start Docker.
For servers in mainland China, you need to configure a Docker image accelerator.
Edit the file /etc/docker/daemon.json with vim and add the following content:
{
"registry-mirrors": [
"https://docker.1ms.run"
]
}
After saving, run systemctl restart docker to restart Docker.
Prepare the Discourse Installation Environment
- Valid SMTP email credentials to send admin account activation emails.
- Your forum domain name must be resolved to your server’s IP address, which is required during installation.
- Install Git on your server using
dnf install gitorapt install git.
After preparing the environment, you can proceed to 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 your server in mainland China cannot connect to GitHub, you can use any of the following proxy services or your own self-hosted proxy:
- GitHub Proxy Acceleration (ghproxy.com)
- GitHub File Acceleration (ghps.cc)
- GitHub File Acceleration (ddlc.top)
Once everything is confirmed correct, you can proceed to install Discourse.
Install Discourse
Run ./discourse-setup to launch the installer.
You will be prompted to enter your forum domain name; enter it and press Enter. The installer will then check your domain’s DNS resolution, and you cannot proceed if the check fails.
If you see the prompt shown above indicating the domain is not correctly resolved, you can manually modify the configuration to install, but this method is outside the scope of this guide. After resolving the DNS issue, re-run ./discourse-setup to launch the installer again.
Next, you will be asked to enter the admin email address, SMTP server, SMTP service port, SMTP username, SMTP password, notification email address, as well as the optional Let’s Encrypt notification email address and Maxmind license. Fill in all information as required.
Finally, a confirmation summary will be displayed. Press Enter to start the installation if all information is correct.
For servers outside mainland China, you only need to wait for the installation to complete. For servers in mainland China, press Ctrl+C to exit the installer and continue with the steps below.
Modifications for Servers in Mainland China
For well-known reasons, you need to modify the configuration file to successfully install Discourse on a server in mainland China. Without this modification, the installation will very likely get stuck at a certain step or even 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.
After completing this change, save and close the file, then run ./launcher rebuild app to start the installation.
(After applying this optimization, you can directly enter the plugin’s GitHub link when configuring plugins, no need to replace it with a mirrored link.)
Post-Installation Steps
Open your forum domain name in a browser, configure your site information and create an admin account.
Activate your admin account via email and log into the admin dashboard. The installation is now complete; congratulations, you now have your own Discourse forum.
