Detailed installation guide + control panel | Super detailed tutorial for installing discourse + control panel

[zengyunsi (运思 曾)]

I’m a beginner at building websites. Due to my hobby, I want to build a technical exchange community. I’m preparing to build a Discourse and share this tutorial. I hope it will be helpful to friends who need to install Discourse, avoid pitfalls. There are relatively few Chinese tutorials for Discourse, and some tutorials are already outdated. I relied on translation software and spent several days researching.

What you need to prepare to build your own Discourse:

A Hong Kong Alibaba Cloud lightweight cloud server. Plugins downloaded from GitHub on domestic servers are as slow as a snail. Therefore, it is recommended to use Alibaba Cloud Hong Kong’s lightweight cloud or other lightweight servers. Lightweight servers are cheaper and suitable for beginners. The configuration requires memory greater than 2GB, otherwise, installation will fail. If you need to install on a domestic server, you can use pay-as-you-go in Hong Kong, then use the “create image” feature in the platform and clone it to the domestic server. This will save you time from encountering pitfalls.

A short, easy-to-remember domain name that resolves to the server’s IP. .com and .net are recommended; other domains lack distinctiveness. You can search for domain names at Bulk Domain Search and use rule-based queries for shorter ones.

System: Ubuntu 20.04, which is commonly used.

After activating a new server, open all firewall ports first (after debugging, close unnecessary ports according to your needs, leaving only the ones in use to avoid hacker attacks). Set the root password in the control panel, then directly SSH into the server via the web browser, or download an SSH client like XTerminal.

Then paste the following three commands and press Enter to execute. When prompted with options, press ‘yes’ to update system sources and install git.

apt update
apt upgrade -y
apt install git

Then paste the following three commands and press Enter to execute as administrator. This step, sudo -s, if not done carefully, may lead to prompts of mysterious creation failures during installation, causing the installation to fail due to lack of permissions.

sudo -s
git clone https://github.com/discourse/discourse_docker.git /var/discourse
cd /var/discourse
chmod 700 containers

After downloading, run the installation wizard.

./discourse-setup

Then, follow the prompts to enter the domain name to be bound. The first installation takes a long time. It is recommended to fill in random information for other domains except the main domain initially, and then rebuild after successful installation. If you don’t understand something, you can use screenshots with WeChat’s image translation. For emails, you can use Alibaba Cloud’s email service.

Then there will be a prompt to continue installation or cancel by pressing Ctrl+C. It is recommended to continue the installation.

After the installation is complete, accessing the bound domain name and seeing the registration page indicates that Discourse has been successfully installed.

Then install a 1Panel. This step is mainly for installing other website programs and for beginners to manage easily. Compared to Baota, this panel is much simpler, cleaner, and has fewer ads. The installation speed is only a few seconds, unlike Baota, which requires long compilation times for the environment.

Execute the following script:

curl -sSL https://resource.fit2cloud.com/1panel/package/quick_start.sh -o quick_start.sh && sudo bash quick_start.sh

During installation, it will prompt that Docker has already been installed, and then display the login backend.

Follow the prompts, find the backend login, and you can see ‘app’ in the container management, which is Discourse. You can start or stop it here.

Then enter the files and edit app.yml. The main modifications are commented in Chinese.

## this is the all-in-one, standalone Discourse Docker container template
##
## After making changes to this file, you MUST rebuild
## /var/discourse/launcher rebuild app
##
## BE *VERY* CAREFUL WHEN EDITING!
## YAML FILES ARE SUPER SUPER SENSITIVE TO MISTAKES IN WHITESPACE OR ALIGNMENT!
## visit http://www.yamllint.com/ to validate this file as needed

templates:
  - "templates/postgres.template.yml"
  - "templates/redis.template.yml"
  - "templates/web.template.yml"
  ## Uncomment the next line to enable the IPv6 listener
  #- "templates/web.ipv6.template.yml"
  - "templates/web.ratelimited.template.yml"
  ## Uncomment these two lines if you wish to add Lets Encrypt (https)
  - "templates/web.ssl.template.yml"
  - "templates/web.letsencrypt.ssl.template.yml"

## which TCP/IP ports should this container expose?
## If you want Discourse to share a port with another webserver like Apache or nginx,
## see https://meta.discourse.org/t/17247 for details
expose:
  - "80:80"   # http
  - "443:443" # https

params:
  db_default_text_search_config: "pg_catalog.english"

  ## Set db_shared_buffers to a max of 25% of the total memory.
  ## will be set automatically by bootstrap based on detected RAM, or you can override
  db_shared_buffers: "128MB"
  ## Modify the maximum upload size for attachments
  upload_size: 300m
  ## can improve sorting performance, but adds memory usage per-connection
  #db_work_mem: "40MB"

  ## Which Git revision should this container use? (default: tests-passed)
  #version: tests-passed

env:
  LC_ALL: en_US.UTF-8
  LANG: en_US.UTF-8
  LANGUAGE: en_US.UTF-8
  DISCOURSE_DEFAULT_LOCALE: zh_CN

  ## How many concurrent web requests are supported? Depends on memory and CPU cores.
  ## will be set automatically by bootstrap based on detected CPUs, or you can override
  UNICORN_WORKERS: 2

  ## TODO: The domain name this Discourse instance will respond to
  ## Required. Discourse will not work with a bare IP number.
  ## Modify the main domain
  DISCOURSE_HOSTNAME: bbs.izdh.net

  ## Uncomment if you want the container to be started with the same
  ## hostname (-h option) as specified above (default "$hostname-$config")
  #DOCKER_USE_HOSTNAME: true

  ## TODO: List of comma delimited emails that will be made admin and developer
  ## on initial signup example 'user1@example.com,user2@example.com'
  ## Modify administrator email
  DISCOURSE_DEVELOPER_EMAILS: 'xxxx@gmail.com'

  ## TODO: The SMTP mail server used to validate new accounts and send notifications
  # SMTP ADDRESS, username, and password are required
  # WARNING the char '#' in SMTP password can cause problems!
  ## Modify sender email server
  DISCOURSE_SMTP_ADDRESS: smtpdm.aliyun.com
  ## Modify sender email port
  DISCOURSE_SMTP_PORT: 80
  ## Modify to automatic sender email account
  DISCOURSE_SMTP_USER_NAME: xxxx@xxx.net
  ## Modify sender email password
  DISCOURSE_SMTP_PASSWORD: "dj6bCRxoHt25NcD6"
  #DISCOURSE_SMTP_ENABLE_START_TLS: true           # (optional, default true)
  DISCOURSE_SMTP_DOMAIN: smtpdm.aliyun.com
  ## Modify to automatic sender email account
  DISCOURSE_NOTIFICATION_EMAIL: xxxx@xxx.net
  DISCOURSE_SMTP_ENABLE_START_TLS: false
  ## If you added the Lets Encrypt template, uncomment below to get a free SSL certificate
  LETSENCRYPT_ACCOUNT_EMAIL: me@example.com

  ## The http or https CDN address for this Discourse instance (configured to pull)
  ## see https://meta.discourse.org/t/14857 for details
  #DISCOURSE_CDN_URL: https://discourse-cdn.example.com
  
  ## The maxmind geolocation IP address key for IP address lookup
  ## see https://meta.discourse.org/t/-/137387/23 for details
  #DISCOURSE_MAXMIND_LICENSE_KEY: 1234567890123456

## The Docker container is stateless; all data is stored in /shared
volumes:
  - volume:
      host: /var/discourse/shared/standalone
      guest: /shared
  - volume:
      host: /var/discourse/shared/standalone/log/var-log
      guest: /var/log

## Plugins go here
## see https://meta.discourse.org/t/19157 for details
## Install 2 plugins
hooks:
  after_code:
    - exec:
        cd: $home/plugins
        cmd:
          - git clone https://github.com/discourse/docker_manager.git
          - git clone https://github.com/discourse/discourse-solved	 
          - git clone https://github.com/discourse/discourse-reactions

## Any custom commands to run after building
run:
  - exec: echo "Beginning of custom commands"
  ## If you want to set the 'From' email address for your first registration, uncomment and change:
  ## After getting the first signup email, re-comment the line. It only needs to run once.
  #- exec: rails r "SiteSetting.notification_email='info@unconfigured.discourse.org'"
  - exec: echo "End of custom commands"

After modifying and saving, return to the terminal, use the command or stop the container in the backend, and then rebuild. However, it seems that if you don’t install this panel, you don’t need to stop the container. Rebuilding directly after installing this panel without stopping the container will result in an error.

./launcher stop app
./launcher bootstrap app`

Wait for the rebuild to complete, then execute the container start command.

./launcher start app

When you access Discourse, it will prompt you to send an email for activation. If you don’t receive it, you can use the following command to create an administrator account and skip it directly. Then, set the language to Chinese in the settings on the left. There is also a place to test email sending, which will prompt for the error reason. You can try a few more times to succeed.

./launcher enter app
rake admin:create

If you need to create other websites, refer directly to the official tutorial. It’s simple, so I won’t go into detail. You can also create a new environment on the website, change the website permissions to 777, and then install various programs.

The main problem solved is that you can run multiple websites on one server, which saves server costs and is more suitable for beginners.

Later, when testing email sending, I discovered a problem:
The settings for these containers, editing app.yml, do not seem to take effect after rebuilding. It needs to be modified in the container environment variables. However, it only takes 5-6 seconds to take effect. It’s still unclear if it affects plugin installation.

Running alongside other websites seems to involve first creating a reverse proxy, then changing the default container’s 443 port to a port like 10443, and then configuring the certificate to enable normal access.

Reverse Proxy

Configure Certificate

[Lhc_fl (Linca)]

@zengyunsi

Then paste the following three commands and press Enter to execute them. Use administrator privileges to download the discourse program, create a directory, and then set high permissions. If this step is not performed carefully, some prompts of inexplicable creation failures will appear during installation, leading to installation failure, because it is caused by lack of permissions.

sudo -s
git clone https://github.com/discourse/discourse_docker.git /var/discourse
cd /var/discourse
chmod 700 containers

In truth, the location to which one clones the discourse_docker repository is immaterial, as it will invariably be installed automatically to the /var/discourse directory…

@zengyunsi

These container settings, editing app.yml, rebuilding does not seem to work. It needs to be modified in the container environment variables. However, it only takes 5-6 seconds to take effect. It is not yet clear whether it affects plugin installation.

In theory, it seems rather improbable. The proper procedure would be to modify the app.yml file and subsequently rebuild the application.

[zengyunsi (运思 曾)]

But editing the configuration file, I found that rebuilding didn’t work, and changing the environment variables in the container took effect in seconds, saving the trouble of rebuilding. Whether the plug-in has any effect is temporarily unclear.

Before, I didn’t type
sudo -s
and kept getting errors, and I didn’t know where the problem was…

Master, do you know how to use the API with a Chinese username? The header cannot contain Chinese characters.

I say, tinkering with the configuration file proved fruitless, as the rebuild didn’t take effect. However, altering the container’s environment variables worked like a charm in mere seconds, sparing me the bother of rebuilding. The impact on plugins remains uncertain for the time being.

Previously, I’d neglected to enter ‘sudo -s’, resulting in a barrage of error messages. I was utterly flummoxed as to the source of the problem.

I say, old chap, might you know how a Chinese username could utilise the API? The header, you see, mustn’t contain Chinese characters.

[Lhc_fl (Linca)]

Huh, is there such a problem? Please paste the logs.

Oh, I say, is that truly the issue? Perhaps you could share the log entries with me.

[zengyunsi (运思 曾)]

Unicode usernames

1: the header cannot contain Chinese characters 2: utf8 refers to the content in the post, not the header 3: Discourse is not decoded by UrlEncode, it will show that the username does not exist. The following test data is provided https://www.baowei.ink/posts.json { "title": "标题标题标题标题标题", "raw": "标题标题标题标题标题标题标题标题标题标题", "category": 10, } Pass Content-Type: application/json; charset=UTF-8 Api-Key: «redacted» Api-Username: system Fail Content-Type: application/json; charset=UTF-8 Api-…

The advice said it was possible, but no matter how I tried, I simply couldn’t manage it…

[Lhc_fl (Linca)]

Use the Discourse API ruby gem

So you want to use Discourse API? Great! Let’s get started. Set up Discourse development environment Set up Discourse development environment using our Windows, OS X or Ubuntu guide. Clone Discourse API Gem Now that you have set up Discourse development environment, you should already have Git and Ruby installed on your system. You can install Discourse API gem by running following command from console: git clone https://github.com/discourse/discourse_api.git ~/discourse_api Install depend…

If feasible, perhaps we could give this a go. Heaven knows what encoding your request utilised.

[go_ahead]

To actually see a Chinese post in the forum

Could the thread starter share their experience in building the forum?

[zengyunsi (运思 曾)]

I’m a novice as well, and I reckon content should be the primary focus, with technology playing a supporting role. At present, I’m rather perplexed about how to utilise Qiniu Cloud for content storage, and I’m equally uncertain about the most effective methods for attracting traffic to my platform.

[zengyunsi (运思 曾)]

Subsequently, a flaw was uncovered. The ‘upload_size: 300m’ setting proved ineffective in regulating attachment dimensions. The root cause remained elusive, compelling me to forgo the installation of the control panel altogether.

[go_ahead]

我是用的亚马逊S3

不过阿里oss也兼容S3了，你可以试试

确实，搭好就看怎么弄内容了

I am utilising Amazon S3 for my storage needs.

However, it’s worth noting that Alibaba OSS has now become compatible with S3. You might consider giving it a try.

Indeed, once the infrastructure is in place, the focus shifts to populating it with content.

[go_ahead]

@honeymoose

The default upload size is 10 MB.

You need to add the above parameter to the Discourse configuration file and then recompile.

After making the changes, enter the directory: /var/discourse and run the command:

./launcher rebuild app

to recompile.

Backend Management Interface Modifications

Simply modifying the configuration file above is not enough; adjustments must also be made within the backend management interface.

You should modify it according to his suggested method.

I recall when I made alterations at the time, I too adjusted parameters and refactored. I utilised Tencent Cloud, and each refactoring required a proxy connection. It was an absolute nightmare to sort out.

[go_ahead]

@Lhc_fl @zengyunsi Is there any way to implement forum username field protection? The custom settings only include sensitive word filtering and permitted user fields.

[honeymoose]

Support for Chinese Unicode usernames: Discourse accommodates Chinese usernames - Discourse - iSharkFly

[Lhc_fl (Linca)]

However, what is username field protection? Does modifying a username require review?

If it’s the former, Discourse does not have native functionality for this. It is recommended to consider developing a plugin.

Alternatively, you could simply review all usernames on the site periodically to check for issues.

@go_ahead Also, I suggest opening a separate thread in English or a mix of Chinese and English to ask this question. This is because off-topic posts in the meta section will be split into separate threads.

Asking in Chinese will also cause inconvenience to several moderators who do not speak Chinese, as it is not easy for them to understand what we are discussing.

Whilst I understand your query, allow me to elucidate on the concept of username field protection and the necessity for username modifications to undergo a vetting process.

If that is indeed the case, Discourse lacks such a native functionality. I would suggest contemplating the development of a bespoke plugin to address this requirement.

Alternatively, you might consider conducting periodic reviews of all usernames across the platform to identify any potential issues.

@go_ahead Furthermore, I would recommend posing your question in English or a combination of English and Chinese in a separate thread. This approach is preferable, as off-topic discussions in the meta section are typically subject to thread separation.

Utilising Chinese exclusively may prove challenging for our non-Chinese speaking moderators, as they may struggle to comprehend the subject matter of our discourse.

[go_ahead]

I seem to have found this feature, this is it.

[go_ahead]

Alas, my command of the English language is woefully inadequate, and I find myself lacking in experience when it comes to communicating with them. I shall endeavour to be more mindful of this matter henceforth. I am most grateful for your guidance!

[honeymoose]

According to my understanding, moderators typically categorise topics containing Chinese content under the ‘chinese-translation’ tag.

Generally speaking, the issue is not particularly significant, and one could also provide an English summary beneath one’s post.

In truth, it’s not overly problematic, as moderators can utilise translation software to garner a general understanding. The matter is of little consequence.

[honeymoose]

@zengyunsi

我是一个做网站菜鸟，因为兴趣爱好，想搭建一个技术交流社区，准备搭建一个discourse，分享这篇教程，希望对有需要安装discourse的朋友，有帮助，避免踩坑，discourse的中文教程比较少，有的教程已经过时了，全靠翻译软件，研究了好几天。

🇨🇳 Discourse Official Install Guide | Discourse 云平台安装 这个内容应该还是可以用的。

但，我们用的是纯服务器，是从 Docker 容器开始的，可能没有用到控制台方面的配置。

The official Discourse installation guide referenced in the Chinese text is likely still applicable. However, it’s worth noting that our implementation utilises bare metal servers, commencing with Docker containers. As such, we may not have employed the console-related configurations mentioned in the guide.

This approach, starting from Docker containers on pure servers, potentially diverges from the standard installation process, particularly in terms of console setup and management. It’s crucial to bear this distinction in mind when following the official guide, as certain steps may need to be adapted or omitted to suit our specific deployment method.

[zengyunsi (运思 曾)]

说的是api ，没办法用中文调用

I’m afraid the API doesn’t support Chinese language input.

[zengyunsi (运思 曾)]

It appears the issue may lie with this particular panel… Perhaps it’s best to revert to the original method and perform a clean installation. I’m inclined to utilise Qiniu Cloud for this purpose.