Read Only Modes in Discourse

Documentation Site Management
, ,
1

:bookmark: This guide explains the various read-only modes available in Discourse, how to enable and disable them, and the scenarios in which you might want to use each mode.

:person_raising_hand: Required user level: Administrator

Managing a vibrant online community on Discourse occasionally requires administrators to temporarily limit user activities. These situations can range from performing server maintenance, facilitating backups, or transitioning servers. During such times, it’s crucial to restrict forum activities without entirely shutting down user access.

Discourse offers various Read-Only Modes administrators can enable to temporarily freeze different types of interactions within a site.

This guide explores these modes, specifically focusing on how to enable and disable them, including handling situations where certain modes intersect.

Understanding Read-Only Modes

Discourse supports two different levels of Read-Only modes tailored to fit various administrative needs. These are:

  1. Full Read Only-Mode
  • Restricts all write operations in the forum, preventing any users from creating or modifying content, such as posting, commenting, or liking.
  • Allows the forum to essentially be “frozen” in its current state, making it so that users can still read and navigate through existing content without impacting the database.
  • Disable changing any Admin site settings or site customizations so that the current state of the database is preserved.
  • Disables new forum logins.
  1. Staff Writes Only-Mode
  • Restricts standard users from write operations in the forum, such as posting, commenting, or liking. Standard users are limited to read-only operations, and will not be able to log into their account once this mode is enabled.
  • Allows Admin and Moderator activities to continue normally. Admins can change site settings, and staff users can perform write operations like posting, liking, or modifying profiles.

These modes ensure flexibility in managing the forum’s operability during critical administrative periods.

How to Enable/Disable Read-Only Modes

:warning: Admins should carefully manage the transition between different read-only modes. Before enabling any read-only mode, ensure that any previously activated one is disabled.

Full Read-Only Mode

Via Rails Console

If you have access to your Discourse installation, use the Discourse rails command line interface to execute the following command after entering your Docker container with ./launcher enter app and then the rails console with rails c:

Discourse.enable_readonly_mode(Discourse::USER_READONLY_MODE_KEY)

Via Admin Panel

If you have administrative access through the web interface, you can navigate to Admin > Backups > Enable Read-Only Mode to enable read-only mode.

image
image1971Ă—298 22.3 KB

To disable Read-Only Mode, execute the following rails command:

Discourse.disable_readonly_mode(Discourse::USER_READONLY_MODE_KEY)

Or, use the admin panel by navigating to Admin > Backups > Disable Read-Only Mode.

image
image1956Ă—381 30.5 KB

Staff Writes Only Mode

:discourse: Staff Writes Only mode can only be enabled / disabled from the Discourse rails console. If your site is hosted by Discourse, please reach out to team@discourse.org if you would like to enable or disable either of this mode.

To enable Staff Writes Only Mode, use the following rails console command:

Discourse.enable_readonly_mode(Discourse::STAFF_WRITES_ONLY_MODE_KEY)

To disable:

Discourse.disable_readonly_mode(Discourse::STAFF_WRITES_ONLY_MODE_KEY)

Best Practices

  • Timely Communication: Inform your community about scheduled read-only periods in advance to set proper expectations.
  • Testing: Before implementing these modes during critical operations, conduct tests during low-traffic periods to understand their impact.
  • Documentation: Keep detailed records of when and why each mode was enabled or disabled to assist in future operational planning.

FAQs

  • How long does it take to enable/disable Read-Only Mode?

    • The change is immediate. However, user experience may vary slightly depending on their actions during the transition period.

  • Help! I’m locked out of my site because of read only mode - what can I do to access my site again?

  • I noticed that there are other READ-ONLY modes listed in discourse/lib/discourse.rb, what do these modes do?

    • READONLY_MODE_KEY is mainly used for the backup and restore process and is triggered by the application itself. This mode can also be enabled or disabled from the the Discourse command line interface with discourse enable_readonly and discourse disable_readonly. However, this key will not survive a container restart.
    • USER_READONLY_MODE_KEY is used when an admin clicks the readonly only button in the admin interface. The special thing about this key is that we do not set it as an expiring key since readonly enabled by a user needs to survive container restarts. Other keys are set with a TTL of 60 seconds and we have a thread to extend the expiry every 30 seconds to ensure that an app is never stuck in readonly mode.
    • PG_READONLY_MODE_KEY and PG_FORCE_READONLY_MODE_KEY are used for PG failover. The former is set as an expiring key while the latter is non-expiring.

Last edited by @tshenry 2024-08-20T02:00:23Z

Check documentPerform check on document:
7 Likes
2

I can’t see a difference! Could these descriptions be tweaked accordingly, if indeed there is a difference?

1 Like
3

I’ve updated the guide to provide some additional clarity here, please let us know if you still have any questions about any of the read-only modes. :slightly_smiling_face:

1 Like
4

But what does

discourse enable_readonly do?

It uses READONLY_MODE_KEY, which sets that ttl to 60, so it turns back off at some point. Now I see that

Is there some reason that this is the default behavior for this command? It’s taken me nearly a decade to learn that this command is totally different from the web interface readonly mode even after being burned a bunch of times. And I now remember that someone tried to tell me about these keys once and I failed to understand their significance.

IMHO a much more sane thing for discourse enable_readonly to do would be to do a Discourse.enable_readonly_mode(Discourse::STAFF_WRITES_ONLY_MODE_KEY). I wish I’d noticed that many years ago!

Could I submit a PR something like this:

  desc "enable_readonly", "Enable the readonly mode, allowing staff writes"
  def staff_writes_only
    load_rails

    Discourse.enable_readonly_mode(Discourse::STAFF_WRITES_ONLY_MODE_KEY)
    puts 'The site is now in readonly mode with staff writes permitted.'
  end
6

I’m not too familiar with this, but I think it would be confusing for enable_readonly_mode to set the site to a staff_writes_only_mode. They are different modes, when doing certain operations, you’d want staff to not be allowed writes on the DB (during a restore, for example, they’ll get removed).

Maybe instead we can do a few other things here:

  1. clarify that the readonly moed sets a TTL in that task’s description
  2. add a task that invokes keep_readonly_mode so it can be extended to more than 60 mins
  3. add enable_staff_writes_only and disable_staff_writes_only tasks
2 Likes
7

I would agree, but it would be much less confusing than “set read only mode for a while”.

I’m pretty sure that the restore script sets read-only mode itself, so it’s not affected by this command.

I’d rather it proclaim that it is set for X minutes when it’s set. It’s not that easy to find the description.

Perhaps. I’m not clear who would use it.

That would be great!

Also, we need to be clear that we’re not conflating the rake tasks with the commands available through the discourse command.

2 Likes
8

Makes sense. Any chance you can submit this as a PR? Same for the enable_staff_writes_only and disable_staff_writes_only commands, if possible. Thanks!

3 Likes