This topic is a linked part of a larger work: “Edgeryders Communities Platform Manual”
- 5.1. Set the SSO secret
- 5.2. Make the basic configuration settings
- 5.3. Add the site to the federation menu
- 5.4. Creating a site contact user
- 5.6. Disable the Discourse Dark theme
1. Making a Discourse multisite installation
Discourse supports multisite installations out of the box. However, we made some changes and fixes and provide our code in the multisite branch of edgeryders/discourse.
By installing from that codebase, you will get the same multisite setup that we use. We will regularly update this branch to the most recent state (HEAD) from discourse/discourse, but only do this about every 3-12 months.
We did not follow the default Discourse installation instructions (which are about a Docker image and Nginx) but rather use a Discourse + Apache 2 + SSL setup without Docker. Good hints to achieve that are:
- Discourse without Docker
- Rails Server with Apache + Puma (via reverse proxy)
- HOWTO setup Discourse with Let’s Encrypt and Apache SSL
[TODO: Detailed installation instructions.]
2. Adding a Discourse site to the multisite setup
The following instructions assume you use Apache 2 as your webserver.
Point the domain to the server with your Discourse installation.
Create a new website record in your Apache 2 configuration, and include the following into the VirtualHost config. It provides the proxy server configuration for Apache 2 to forward to Puma (the Rails server providing Discourse on an internal port), with exceptions for static files etc. that should be served by Apache directly.
Enable a redirection from the
wwwsubdomain to the naked domain.
Add the multisite to
Create the database (supply your database name suffix for
createdb discourse_production_sitename -U discourse
Migrate the database (supply the correct database name at
cd /home/discourse/production_multisite/current; RAILS_DB=… bundle exec rails db:migrate['multisite']`;
sudo monit restart puma_discourse_multisite_production
3. Configuring a Discourse site to be the default site
Each Discourse multisite installation has one “default” site. This is only relevant for Sidekiq: unlike in “normal” Discourse installations, the Sidekiq queue in a multisite installation processes the tasks of all sites in the multisite group.
Due to this, it should only be accessible to the server administrator and not to any Discourse administrator of any one Discourse site of the multisite group. To achieve this, Sidekiq looks at the servername of the Discourse server process and only grants a Discourse administator access to
/sidekiq if that is the same as the servername used to access Discourse. This servername is that of the “default” site of a Discourse multisite set.
We propose to configure one Discourse multisite site with the sole purpose of providing access to this
/sidekiq URL, as follows:
Mark this site of the multisite set as the default one in the Discourse configuration. [TODO: How to do that.]
In the site’s Apache Virtualhost configuration file provided above, change the proxy exception for uploaded images to be as follows:
<location /uploads/default> ProxyPass ! </location>
In the site’s Apache Virtualhost configuration file provided above, change the proxy server forwarding to use the domain name (example.com) of the default site instead of
127.0.0.1, as follows:
ProxyPass / http://example.com:9294/ ProxyPassReverse / http://example.com:9294/
This type of forwarding is obviously slower as it goes via the Internet rather than the local loop interface for
127.0.0.1, but as the default site is only used to access the Sidelkiq interface it does not matter here.
4. Configuring a Discourse site to be the SSO provider
The Discourse multisite system just means “one codebase, one process set, multiple databases”. All Discourse platforms in a multisite set are completely independent and can use their own login and signup mechanism. Using SSO (single-sign-on) is completely optional when using a Discourse multisite setup – we chose to do so as part of our federated Discourse hosting.
Out of the box, Discourse can be configured to be either the SSO provider or an SSO client for the single-sign-on mechanism. In our setup, one of the Discourse multisite platforms is the SSO provider and all others are SSO clients.
We configured communities.edgeryders.eu to be the SSO provider and called it the “Edgeryders Communities Login Site”. Putting it on a subdomain of our main platform edgeryders.eu is meant to create the least amount of confusion for the bulk of users compared to a process where they would all be forwarded to another domain for login.
We made the following adaptations to let Discourse work as a SSO provider without much friction:
Configure Discourse as SSO provider in the Discourse admin interface under “☰ → Admin → Settings”:
- Login → enable sso: false
( This setting must only be enabled if you want Discourse to act as the SSO client.)
- Login → enable sso provider: true
- Login → sso secret: (put in a random passphrase string)
- Login → enable sso: false
Hide everything of the Discourse user interface for non-staff users (using theme CSS overwrites) except the following:
- user menu → Edit Profile
- user menu → Logout
Put in prominent links to the manual for help with signup, login and site usage. In our case we have a top navbar link (with yellow background) to signup help and a link in the hamburger menu to the whole manual.
Create a topic that users will see at the end of the signup process, with the following information:
- A message “You have successfully activated your account and logged in.”
- A call to action: “Return to the community you want to join”
- A list of the federated Discourse websites where users can go back to, with icons and links leading to https://example.com/login . Using that link target instead of https://example.com/ will automatically log in users when they return to the site where they started the signup process.
- An explanation of what the login site is for.
Set the topic that should be visible at the end of the signup process as a “global banner topic”. This will make it visible, given that you have hidden all Discourse content by CSS.
Hide the “close” button of the banner topic by CSS, to make sure it will always be visible to all logged-in users.
5. Configuring a Discourse site to be a federated forum
These tasks are mostly specific to the Edgeryders Communities platforms, a hosting offer of federated Discourse platforms by Edgeryders OÜ.
5.1. Set the SSO secret
Get the current value of the SSO secret from an existing Discourse website that you configured as a federated Discourse platform (so not from your SSO provider), by looking at: https://example.com/admin/site_settings/category/all_results?filter=sso
Set the SSO secret as follows. First, enter Rails console (supply your database name for
cd /home/discourse/production_multisite/current; RAILS_DB=discourse_production_sitename RAILS_ENV=production bundle exec rails c
Inside Rails console, execute this command (supply your SSO secret for
SiteSetting.create!(name: 'sso_secret', data_type: 1, value: "sso_secret")
5.2. Make the basic configuration settings
If you use our codebase, most of these settings will already be done (and in addition, useful defaults will be provided for other Discourse settings) via our plugin EdgerydersMultisite.
Otherwise, you can make the settings manually:
Run the setup wizard by visiting https://example.com/wizard
Upload logos and favicons, either as part of the setup wizard or by visiting at any later time https://example.com/wizard/steps/logos
Make the following settings in the Discourse admin interface under “☰ → Admin → Settings”. (These are essential for the login mechanism and external user profile mechanism to work properly.)
- Users → Email editable: false
- Security → Force Https: true
- Login → enable_sso: true
- Login → sso overrides email: true
- Login → sso overrides username: true
- Login → sso overrides avatar: true
- Login → sso overrides profile background: true
- Login → sso overrides card background: true
5.3. Add the site to the federation menu
We created a custom plugin EdgerydersCommunitiesNavigation that provides the top-right “Communities” menu, linking all our federated Discourse platforms together. To add the new site:
Add a new menu entry in file edgeryders_communities_navigation.hbs.
Deploy the code. This will change the top-right federation menu on all sites of the Discourse multisite group at once.
5.4. Creating a site contact user
In the recent versions of Discourse, the
system user can no longer be renamed, but you can (and should) configure in setting “site contact username” that a different user account is used by the software to send messages etc…
Here is how to create and maintain such a user account for one specific Edgeryders Communities platform (the “target platform”):
Create a new user account on communities.edgeryders.eu using:
- the target platform’s name as the username
- a fictive e-mail address that belongs to the target platform’s domain – for example,
email@example.com the case of this platform
- a password that you won’t remember. as it will never be needed
Log in as an admin user on communities.edgeryders.eu.
Go to “Admin → Users → New”, select the user account you just created, and click Activate Account. This verifies the non-existing e-mail address.
Upload the platform logo as the user’s profile image.
Go to the target platform and click “Log in”, to create an account with the same username there and sync the profile image.
Log in with an admin account on the target platform and make the new user a moderator. This will indicate it is an “official” account. (Do not make it admin, as that is not shown in the frontend anyway but would be more dangerous in case the account is ever compromised or somebody gets access to the “non-existing e-mail address”.)
Set the Discourse setting “site contact username” to that user, which makes it take over most roles of the
If you ever have to adapt the username or profile picture of this special user, do so by logging in as admin on communities.edgeryders.eu and impersonating that user. (Re-)log in to the target platform as that user afterwards to sync the changes to that platform. Since we use SSO, username, e-mail address and profile picture cannot be changed at all on Edgeryders Communities platforms directly, not even by admins.
5.6. Disable the Discourse Dark theme
Because it’s not yet ready to work with our custom modifications in Discourse.
- Go to
- Disable “Theme can be selected by users”.
6. Discourse multisite administration
[TODO: Content of this section.]
6.1. Rake tasks
Some multisite specific Rake tasks for Discourse are available.