Using Hidden Site Settings

Documentation Self-Hosting
, ,
1

:bookmark: This is a how-to guide about Hidden Site Settings, how to enable them, and why you might want to adjust them.

:person_raising_hand: Required user level: Administrator
:warning: Important: Console access is required for some steps.

In Discourse, hidden site settings refer to configuration options that are not readily visible or accessible through the standard admin dashboard interface. These settings are part of the backend configuration that can control various advanced or potentially impactful features of the site.

These hidden settings come with default values pre-configured, which are set to ensure optimal performance and security based on common use cases and best practices.

Hidden settings are concealed from the default settings interface to prevent accidental misconfiguration by admins who may not fully understand their implications. They are intended for:

  • Administrators who have a deep understanding of Discourse’s inner workings.
  • Specific cases where unusual or very specific site configuration is necessary.
  • Testing or experimental features that are not yet ready for general use.

Admins who wish to modify hidden settings typically need to do so because the default configuration doesn’t perfectly align with their needs.

:warning: Important Notes on Hidden Settings:

Adjusting hidden site settings in Discourse can lead to various issues such as security vulnerabilities, negative performance impact, user experience degradation, or data loss if not done carefully!

Hidden site settings should only be modified by knowledgeable Discourse administrators. Before changing a setting, be sure to understand what it does and the implications of the change. When possible, implement significant configuration changes in a staging or development environment. Before making broad or critical changes, ensure backups are up-to-date to restore the forum’s state if something goes wrong.

How to Edit Hidden Site Settings

Option 1: Rails Console

To modify hidden site settings, you typically need to use the Rails console, a command line tool that allows you to interact directly with the backend of your Discourse installation. To adjust settings via the rails console you can follow these steps:

  1. Access the Rails Console:
cd /var/discourse
./launcher enter app
rails c
  1. Change a Setting:
SiteSetting.your_setting_name = new_value

Replace your_setting_name with the name of the setting you want to modify, and new_value with the value you want to set.

  1. Exit the Console:
exit

Option 2: Setting Up Environment Variables in app.yml

You can also use environmental variables to adjust hidden site settings. The app.yml file is a configuration file used in Docker-based deployments of Discourse. It is typically located in the /containers directory of your Discourse installation. Here’s how you can add or modify environment variables:

  1. Access the app.yml File:
    Open the app.yml file in your preferred text editor:
nano /var/discourse/containers/app.yml
  1. Add Environment Variables:
    Environment variables can be configured in the env section of the app.yml file. They follow the pattern DISCOURSE_SETTING_NAME: value. For example, to set a the max_category_nesting setting to 3 through an environment variable, you would use:
env:
  DISCOURSE_MAX_CATEGORY_NESTING: 3
  1. Rebuild the Container:
    After saving changes to the app.yml file, rebuild the Discourse Docker container to apply the changes:
cd /var/discourse
./launcher rebuild app

Why Enable Hidden Settings

Enabling or adjusting hidden site settings in Discourse allows administrators to deeply customize their forum setup to meet specific technical requirements, enhance performance, or ensure security and compliance, thus supporting a finely tailored user experience and operational efficiency.

Examples of hidden site settings include:

  • Badge SQL: Enabling enable badge sql allows site administrators to create custom SQL queries for badge criteria, offering flexibility in badge assignment based on complex conditions.
  • Permanent Post Deletion: Enabling can permanently delete allows the permanent deletion of posts for compliance or privacy concerns.
  • S3 Backup Settings: Including S3 uploads in backups with include_s3_uploads_in_backups can be used for enhanced backup strategies.
  • Search Rate Limits: Adjusting search rate limits with settings such as rate_limit_search_user to prevent throttling in high-usage scenarios.

FAQs

Q: Can hidden settings be made visible in the UI?
A: Hidden settings in Discourse are not directly configurable via the UI for safety and complexity reasons.

Q: Where can I find information about each hidden setting?
A: Detailed information about each setting can be found within the Hidden Site Settings Reference Guide and Discourse source code, specifically in the site_settings.yml file on the GitHub repository. Additional information about some settings is also available on the Discourse Meta forums.

Q: Do changes made through environment variables persist through updates?
A: Yes, if set in app.yml or the system’s permanent profile, these settings will persist through updates unless overwritten by other configurations.

Q: How do I know which settings can be controlled via environment variables?
A: Typically, any Discourse site setting can be prefixed with DISCOURSE_ and set as an environment variable.

Q: Is it safe to configure sensitive information via environment variables?
A: Environment variables are generally considered safe for configuration management. However, ensure they are not exposed in shared or insecure environments.

Q: Do I need to rebuild if I toggle a site setting?
A: In most cases, toggling a site setting via the rails console does not require a rebuild of your Discourse setup. These changes typically take effect immediately or upon a refresh of your instance. However, some specific settings, especially those that influence the foundational aspects of the system, might require a restart or rebuild for the changes to apply. For changes made in the app.yml file, a rebuild of your Discourse container is required for those changes to take effect.

Q: Can I revert a setting change easily?
A: Yes, most settings can be reverted unless they involve data deletion.

Additional Resources

Last edited by @hugh 2024-12-16T11:39:02Z

Check documentPerform check on document:
5 Likes