Initializer

There are some settings that you will need to change in the config/initializer/decidim.rb file. We recommend that, whenever it is possible, you use Environment Variables, as just cleaner and easier to work with.

If you need to add special logic or if you feel more comfortable working with Ruby code instead of Environment Variables, then you can of course do all the changes that you need directly in the initializer file. Take into account that this file could be published in a Version Control System (like git) so you should be careful with the secrets/API keys that you add here.

Remember to restart your server when making changes in this file.

This is where you can change the behaviour defined on the different components (most notably from decidim-core).

After making changes to this file you will need to also restart your application server.

Application name

The name of the application.

  config.application_name = "My Application Name"

Default mailer sender

The email that will be used as sender in all emails from Decidim.

  config.mailer_sender = "change-me@domain.org"

Available locales

Sets the list of available locales for the whole application.

When an organization is created through the System area, system admins will be able to choose the available languages for that organization. That list of languages will be equal or a subset of the list in this file.

  config.available_locales = [:en, :ca, :es]

Restrict system access

For extra security, restrict access to the system part with an authorized ip list. You can use a single ip like ("1.2.3.4"), or an ip subnet like ("1.2.3.4/24") You may specify multiple ip in an array ["1.2.3.4", "1.2.3.4/24"]

  config.system_accesslist_ips = ["127.0.0.1"]

Default locale

Sets the default locale for new organizations. When creating a new organization from the System area, system admins will be able to overwrite this value for that specific organization.

  config.default_locale = :en

Content Processors

Defines a list of custom content processors. They are used to parse and render specific tags inside some user-provided content. Check the Content Processor docs for more info.

  config.content_processors = []

Force SSL

Whether SSL should be enabled or not. Recommended for extra security.

  config.force_ssl = true

CORS enabled

The SVG do not support CORS. When using custom asset host different than root url, set this value to true, in order to activate the available workaround.

Please refer to:

  config.cors_enabled = true

Geocoder configuration

Allows to make geographical mapping in some components, like Proposals or Meetings. It must be configured against a OpenStreetMap provider. See Geocoder service documentation.

  config.geocoder = {
    static_map_url: "https://image.maps.ls.hereapi.com/mia/1.6/mapview",
    here_api_key: Rails.application.secrets.geocoder[:here_api_key]
  }

Custom resource reference

Custom resource reference generator method. See the See System panel docs for more information.

  config.reference_generator = lambda do |resource, component|
    # Implement your custom method to generate resources references
    "1234-#{resource.id}"
  end

Currency unit

Allows to change the currency unit, for instance to $. By default is €.

  config.currency_unit = "€"

Image uploader settings

Quality

Defines the quality of image uploads after processing. Image uploads are processed by Decidim, this value helps reduce the size of the files.

  config.image_uploader_quality = 80

Attachment file size

The maximum file size of an attachment

Mind that this depends on your environment, for instance you could also need to change your web server configuration (nginx, apache, etc).

  config.maximum_attachment_size = 10.megabytes

User avatar file size

The maximum file size for a user avatar

Mind that this depends on your environment, for instance you could also need to change your web server configuration (nginx, apache, etc).

  config.maximum_avatar_size = 10.megabytes

Reports

The number of reports which a resource can receive before hiding it.

  config.max_reports_before_hiding = 3

Custom HTML Header snippets

The most common use is to integrate third-party services that require some extra JavaScript or CSS. Also, you can use it to add extra meta tags to the HTML. Note that this will only be rendered in public pages, not in the admin section.

Before enabling this you should ensure that any tracking that might be done is in accordance with the rules and regulations that apply to your environment and usage scenarios. This component also comes with the risk that an organization’s administrator injects malicious scripts to spy on or take over user accounts.

  config.enable_html_header_snippets = false

Track newsletter links

Allow organizations admins to track newsletter links, trough UTMs. See UTM parameters in Wikipedia.

  config.track_newsletter_links = true

Download your data expiry time

Amount of time that the download your data files will be available in the server.

  config.download_your_data_expiry_time = 7.days

Throttling settings

Security settings for blocking possible attacks.

Max requests

Max requests in a time period to prevent DoS attacks. Only applied on production.

  config.throttling_max_requests = 100

Period

Time window in which the throttling is applied.

  config.throttling_period = 1.minute

Unconfirmed access for users

Time window were users can access the website even if their email is not confirmed.

  config.unconfirmed_access_for = 2.days

Base path for uploads

A base path for the uploads. If set, make sure it ends in a slash. Uploads will be set to <base_path>/uploads/. This can be useful if you want to use the same uploads place for both staging and production environments, but in different folders.

If not set, it will be ignored.

  config.base_uploads_path = nil

SMS gateway configuration

If you want to verify your users by sending a verification code via SMS you need to provide a SMS gateway service class.

An example class would be something like:

class MySMSGatewayService
  attr_reader :mobile_phone_number, :code, :context
  def initialize(mobile_phone_number, code, context = {})
    @mobile_phone_number = mobile_phone_number
    @code = code
    @context = context
  end
  def deliver_code
    # Actual code to deliver the code
    true
  end
end

Then you will need to configure it in the Decidim initializer:

  config.sms_gateway_service = "MySMSGatewayService"

Timestamp service configuration

Used by decidim-initiatives.

Provide a class to generate a timestamp for a document. The instances of this class are initialized with a hash containing the :document key with the document to be timestamped as value. The instances respond to a timestamp public method with the timestamp.

An example class would be something like:

class MyTimestampService
  attr_accessor :document
  def initialize(args = {})
    @document = args.fetch(:document)
  end
  def timestamp
    # Code to generate timestamp
    "My timestamp"
  end
end

Then you will need to configure it in the Decidim initializer:

  config.timestamp_service = "MyTimestampService"

PDF signature service

Used by decidim-initiatives.

Provide a class to process a pdf and return the document including a digital signature. The instances of this class are initialized with a hash containing the :pdf key with the pdf file content as value. The instances respond to a signed_pdf method containing the pdf with the signature.

An example class would be something like:

  class MyPDFSignatureService
    attr_accessor :pdf

    def initialize(args = {})
      @pdf = args.fetch(:pdf)
    end

    def signed_pdf
      # Code to return the pdf signed
    end
  end

  config.pdf_signature_service = "MyPDFSignatureService"

Etherpad configuration

Only needed if you want to have Etherpad integration with Decidim. See Etherpad’s Decidim docs in order to set it up.

  config.etherpad = {
    server: Rails.application.secrets.etherpad[:server],
    api_key: Rails.application.secrets.etherpad[:api_key],
    api_version: Rails.application.secrets.etherpad[:api_version]
  }

Machine Translation Configuration

To enable machine translations you need to enable the service and specify the class used for translation (this usually is the one contacting an external API from a 3d party service that actually translates the string).

  config.enable_machine_translations = false
  config.machine_translation_service = "MyTranslationService"

An example class would be something like:

  class MyTranslationService
    attr_reader :text, :original_locale, :target_locale

    def initialize(text, original_locale, target_locale)
      @text = text
      @original_locale = original_locale
      @target_locale = target_locale
    end

    def translate
      Actual code to translate the text
    end
  end

See Machine Translations for more information about how it works and how to set it up.

Default CSV column separator

Sets Decidim::Exporters::CSV’s default column separator

  config.default_csv_col_sep = ";"

User Roles

The list of roles a user can have, not considering the space-specific roles.

  config.user_roles = %w(admin user_manager)

Visibility for Amendments

The list of visibility options for amendments. An Array of Strings that serve both as locale keys and values to construct the input collection in Decidim::Amendment::VisibilityStepSetting::options.

This collection is used in Decidim::Admin::SettingsHelper to generate a radio buttons collection input field form for a Decidim::Component step setting :amendments_visibility.

  config.amendments_visibility_options = %w(all participants)

Export fields

To customize export fields, you can subscribe to any serialize event. Every serializer event has unique event name in format: decidim.serialize.module_here.class_here

  initializer "decidim_budgets.serializer_listener" do
    ActiveSupport::Notifications.subscribe("decidim.serialize.budgets.project_serializer") do |_event_name, data|
      # Implement your custom code for new or existing fields.
      data[:serialized_data][:column_title] = "Row data #{data[:resource].class}"
    end
  end

Content Security Policy

Defines additional content security policies following the structure keys are the CSP directives and the values are arrays of allowed sources

List of additional content security policies to be appended to the default ones This is useful for adding custom CSPs for external services like Here Maps, YouTube, X (former Twitter) etc.

Below you will find a the recipe of enabling X (former Twitter) timelines, based on Content Security Policy (CSP) Examples Twitter example. The format is a Hash with the following structure:

  {
    "script-src": %w(platform.twitter.com syndication.twitter.com),
    "style-src": %w('sha256-5g0QXxO6NfvHJ6Uf5BK/hqQHtso8ZOdjlnbyKtYLvwc='),
    "frame-src": %w(platform.twitter.com),
    "img-src": %w(syndication.twitter.com),
  }

Additionally, the following example, will allow you to enable Decidim to properly load YouTube videos:

  {
      "frame-src" => %w(https://www.youtube-nocookie.com/),
  }

The keys are the CSP directives and the values are arrays of allowed sources See CSP in MDN for more information

Please note, we strongly recommend not to use the wildcard (*) as a allowed source!

The default value for this setting is an empty Hash

We are starting from the following rules defined in decidim-core gem:

  {
    "default-src" => %w('self' 'unsafe-inline'),
    "script-src" => %w('self' 'unsafe-inline' 'unsafe-eval'),
    "style-src" => %w('self' 'unsafe-inline'),
    "img-src" => %w('self'),
    "font-src" => %w('self'),
    "connect-src" => %w('self'),
    "frame-src" => %w('self'),
    "media-src" => %w('self')
  }

And we automatically add the assets host to the media-src, img-src, script-src, style-src directives, and the wss protocol to the connect-src directive. To the those rules we are appending the additional content security policies defined at the organization level, if any. The order of the directives is the following:

  1. The default rules defined in decidim-core gem

  2. The content security policies required for serving the assets (defined by asset_host rails config)

  3. The additional content security policies defined by this setting

  4. The additional content security policies defined at the organization level

  config.content_security_policies_extra = {}

Additional Reading:

Etiquette validator configuration

This configuration option is used to enable or disable the etiquette validator in your Ruby on Rails application. The etiquette validator is responsible for ensuring that user-generated content meets specific formatting guidelines.

Description

The etiquette validator is applied to the create and edit forms of Proposals, Meetings, and Debates for both regular and admin users. Admin users can use the admin panel to use these forms. The validator checks for the following conditions:

  • too_much_caps: Ensures that the content does not contain an excessive amount of capital letters.

  • too_many_marks: Ensures that the content does not contain too many punctuation marks.

  • must_start_with_caps: Ensures that the content starts with a capital letter.

Configuration

To disable the etiquette validator, set the following in your application’s configuration file:

config.enable_etiquette_validator = false

Alternatively, you can use an environment variable:

DECIDIM_ENABLE_ETIQUETTE_VALIDATOR