Last edit: Jun 19, 2024

Config is used to control the behavior of the application developed. It is a file located in app/config.yml.

flag default value Explanation
do_not_add_return_to_to_authorization_policies false By default, if the authorization policy fails and is set up to redirect, it automatically appends the return_to parameter. By setting the flag to true, the return_to parameter will not be appended
escape_output_instead_of_sanitize true If disabled, any variable will be sanitized before the output and treated as html and corrected, which is unideal as it can change the expected output. By keeping this flag as true, the output will be escaped, not sanitized. We highly recommend setting this flag to true.
graphql_argument_type_mismatch_mode error Defines behavior when the argument type in the GraphQL query is wrong. Possible values:
warning - display warning message in log
error - raise error, do not allow to deploy query
ignore - silently ignore error
liquid_check_mode error When you deploy/sync liquid files we run static analysis on the files. By keeping this flag as error we gonna throw error if file contains unknown filter.
Possible values:
warning - display warning message in log
error - raise error, do not allow to deploy liquid file
liquid_raise_mode true If diabled, liquid runtime errors will be displayed inline and the code will continue to execute despite error. By keeping this flag as true, whenever there's any Liquid error - like parsing JSON files, providing invalid arguments to GraphQL query, etc., the 500 page will be raised instead and the execution will stop. This is generally the desired and expected behavior and we recommend keeping this flag as true.
require_table_for_record_delete_mutation true The argument table for the record_delete mutation is optional by default, which can lead to security issues if the type of the record is not explicitly checked before executing the mutation. By setting the flag to true, you effectively make the table attribute required to avoid such vulnerability.
safe_translate true If disabled, the translate filter (t is an alias for it) will mark the output as html_safe. This can lead to XSS vulnerability, if you provide user input as a variable, as it could contain malicious JavaScript. In such scenario, you should explicitly use another filter, translate_escape (or t_escape). However, by keeping this flag as true, the system will automatically use the equivalent of t_escape if you provide any variable to the translation key, making your application safer by default. We highly recommend keeping this flag to true.
skip_elasticsearch false If you do not use the keyword argument in records/users queries or customizations/people queries, you can increase performance by avoiding indexing data in the ELasticSearch by setting this flag to true.
slug_exact_match true If disabled, a page with slug abc will match not only example.com/abc, but also URLs like example.com/abc/1, example.com/abc/1/x and to control this behavior, you would need to set max_deep_level Page property. By keeping this flag as true, only example.com/abc will be matched. Additionally, you will be able to use named parameters in the URLss, like /abc/:id. We highly recommend setting this flag to true.
websockets_require_csrf_token true If disabled, the websocket connection will not check the CSRF token. By keeping this flag as true, connections to websocket will require CSRF token to be included in the parameters, increasing the security of your application.
liquid_add_old_variables false Back at a day, there were multiple global objects available, such as page, platform_context, and forms. To simplify the use of platformOS, we have grouped everything into one global object context. Setting this flag to true will re-enable those deprecated global objects.
maintenance { enabled: false, password_constant: 'MAINTENANCE_PASSWORD', partial: 'maintenance' } Allows to setup mandatory password protection, useful when the site should be restricted only to users who know the password.
modules_that_allow_delete_on_deploy [] Allows to list module names, for which if a file will be missing on deploy, it will be removed. The default behaviour of module is to not delete any files, because it is possible that developer would know download all of the source code and would like to just deploy an overwrite for a few chosen files. If the module is listed and sync is enabled, then users will be also able to remove the files from the instance by removing them in their filesystem.
translation_keys_to_ignore [] Allows to list translation keys which will not be updated/delete on sync/deploy. It is most useful if you would like to change translations using UI and will not reflect it in your codebase. Translations will still be created if not defined.
sync_translations false If enabled, translations will be synchronized on each sync/deploy similarly to other resources, meaning if you remove a translation form a translation file and sync it, it will disappear from the Instance. It will also remove all translations from the deleted file. The default behaviour (for backwards compatibility) is that translations will not be deleted; in order to delete a translation one needs to explicitly call admin_translation_unset GraphQL mutation. This setting is compatible with modules_that_allow_delete_on_deploy.
html_format_exact_match false If enabled, platformOS will return 404 for all formats that have not been defined. For example, if app/views/pages/my-page.liquid exists, platformOS will render this page for multiple formats - /my-page, /my-page.php, /my-page.asp. Enabling this setting will render this page only for /my-page.
validations_for_graph_queries false When the feature is enabled, platformOS performs additional consistency validations for specific GraphQL queries, with a primary focus on mutations. These validations are designed to verify that the developer's queries express a valid and well-defined intent. By enforcing these consistency checks, platformOS helps maintain data integrity and prevents unintended or ambiguous mutations from being executed. This feature serves as an additional layer of protection, ensuring that the queries submitted by developers are semantically correct and align with the intended behavior of the application.

Example app/config.yml file with recommended values:

escape_output_instead_of_sanitize: true
graphql_argument_type_mismatch_mode: error
liquid_check_mode: error
liquid_raise_mode: true
require_table_for_record_delete_mutation: true
safe_translate: true
skip_elasticsearch: true
slug_exact_match: true
websockets_require_csrf_token: true
sync_translations: true
liquid_add_old_variables: false

Maintenance - setting up password protection

Example config.yml for enabling password protection:

  enabled: true
  password_constant: 'MAINTENANCE_PASSWORD'
  partial: 'maintenance'

When a user enters the site, and the enabled flag is set to true, they are presented with content from the partial defined in the config, in the above example app/views/partials/maintenance.html.liquid. Inside this partial you can display any html, and most likely you would like to include a form to allow to provide password:

  <form action="/_maintenance" accept-charset="UTF-8" method="post">
    <input type="hidden" name="authenticity_token" value="dCPFDDTyxdvHNwZoX6kxZL1g7uNjvXgKlT5tnPgbMNYIbmkC-cBX0wuGR4pwj62uKe-p4o-RCuNtxjySk8FHNA">
        <input type="password" name="password" id="password" value="" class="password" placeholder="Password" />
        <input type="submit" name="commit" value="Submit" class="btn btn-blue" />

The /_maintenance endpoint is a built-in platformOS endpoint, which verifies that context.params.password is equal to the value of the constant defined in password_constant, in this scenario context.constants['MAINTENANCE_PASSWORD']. If there is a match, platformOS stores the information in the session and the user will not be prompted again to provide the password.


The maintenance page will be displayed only for valid pages and only for GET requests. It means that custom error pages and POST/PATCH/PUT/DELETE will continue to work.


We are always happy to help with any questions you may have.

contact us