### Start Rails server

Source: https://github.com/decidim/decidim/blob/develop/docs/modules/install/pages/index.adoc

Starts the Rails development server.

```console
bin/rails s

```

--------------------------------

### Start the web server with bin/dev

Source: https://github.com/decidim/decidim/blob/develop/docs/modules/install/pages/manual.adoc

Starts the web server. After running this, visit http://localhost:3000 to see the app running.

```bash
bin/dev
```

--------------------------------

### Example response for version query

Source: https://github.com/decidim/decidim/blob/develop/decidim-api/docs/usage.md

Example formatted response from the Decidim GraphQL API for the version query. The actual version number will vary depending on the installation.

```json
{
  "data": {
    "decidim": {
      "version": "0.18.1"
    }
  }
}
```

--------------------------------

### Install decidim-initiatives

Source: https://github.com/decidim/decidim/blob/develop/decidim-initiatives/README.md

Install the decidim-initiatives module by adding the gem, running the upgrade task, and migrating the database.

```bash
bundle add decidim-initiatives
bundle exec rails decidim:upgrade
bundle exec rails db:migrate
```

--------------------------------

### Install dependencies with bundle

Source: https://github.com/decidim/decidim/blob/develop/decidim-comments/README.md

Execute this command after adding the dependency to install the gem.

```bash
bundle
```

--------------------------------

### Install decidim-templates

Source: https://github.com/decidim/decidim/blob/develop/decidim-templates/README.md

Run these commands in your console to install the module. This adds the gem, runs the upgrade task, and migrates the database.

```bash
bundle add decidim-templates
bundle exec rails decidim:upgrade
bundle exec rails db:migrate
```

--------------------------------

### Install decidim-demographics

Source: https://github.com/decidim/decidim/blob/develop/decidim-demographics/README.md

Commands to install the module and run database migrations.

```bash
bundle add decidim-demographics
bundle exec rails decidim:upgrade
bundle exec rails db:migrate
```

--------------------------------

### Install Decidim and generate an application

Source: https://github.com/decidim/decidim/blob/develop/README.adoc

Install the Decidim gem and generate a new Ruby on Rails application. Run these commands in a terminal to get started with Decidim.

```console
gem install decidim
decidim decidim_application
```

--------------------------------

### Initialize database with seeds

Source: https://github.com/decidim/decidim/blob/develop/docs/modules/install/pages/index.adoc

Sets up the database, runs migrations, precompiles assets, and seeds example data. Note that this adds example seed data which may not be desired for production.

```console
bin/rails db:create db:migrate assets:precompile db:seed

```

--------------------------------

### Install stylelint globally

Source: https://github.com/decidim/decidim/blob/develop/docs/modules/develop/pages/guide_commands.adoc

Installs stylelint as a global npm package.

```console
npm install -g stylelint
```

--------------------------------

### Initialize database and seed with example data

Source: https://github.com/decidim/decidim/blob/develop/docs/modules/install/pages/manual.adoc

Creates the database, runs migrations, precompiles assets, and seeds the database with example content. This also creates default data including an administrator account with email admin@example.org and password decidim123456789.

```bash
bin/rails db:create db:migrate
bin/rails assets:precompile
bin/rails db:seed
```

--------------------------------

### Install decidim-design with Bundler and Rails

Source: https://github.com/decidim/decidim/blob/develop/decidim-design/README.md

Run these commands in your console to install the decidim-design module. The commands add the gem, run the upgrade task, and migrate the database.

```bash
bundle add decidim-design
bundle exec rails decidim:upgrade
bundle exec rails db:migrate
```

--------------------------------

### Install decidim-conferences

Source: https://github.com/decidim/decidim/blob/develop/decidim-conferences/README.md

Install the decidim-conferences module by adding the gem, running the upgrade task, and migrating the database.

```bash
bundle add decidim-conferences
bundle exec rails decidim:upgrade
bundle exec rails db:migrate
```

--------------------------------

### Example variables for createDebate

Source: https://github.com/decidim/decidim/blob/develop/docs/modules/develop/pages/api/reference/components/debates/create.adoc

Example JSON variables to submit with the createDebate mutation, including componentId and input attributes.

```json
{
  "componentId": 5,
  "input": {
    "locale": "en",
    "attributes": {
      "description": "Cities need more people, not more cars",
      "taxonomies": [11],
      "title": "More sidewalks and less roads"
    }
  }
}
```

--------------------------------

### Example variables for UpdateBudget

Source: https://github.com/decidim/decidim/blob/develop/docs/modules/develop/pages/api/reference/components/budgets/update.adoc

Example JSON variables for the updateBudget mutation, showing how to set totalBudget and title.

```json
{
  "componentId": "3",
  "budgetId": "5",
  "input": {
    "attributes": {
      "totalBudget": 56700,
      "title": {
        "en": "Budget title changed from API"
      }
    }
  }
}
```

--------------------------------

### Seed example data with bundle exec rails db:seed

Source: https://github.com/decidim/decidim/blob/develop/decidim-initiatives/README.md

Populates the database with example data for the decidim-initiatives engine. Run this command in the Rails application root.

```bash
bundle exec rails db:seed
```

--------------------------------

### Install Node.js 22 and Yarn using nvm

Source: https://github.com/decidim/decidim/blob/develop/docs/modules/install/pages/manual.adoc

Installs Node.js 22 via nvm and the Yarn package manager globally. Requires bash and network access to GitHub.

```bash
curl -o- https://raw.githubusercontent.com/nvm-sh/nvm/v0.40.3/install.sh | bash
source "$HOME/.nvm/nvm.sh"
nvm install 22
npm install -g yarn
```

--------------------------------

### Install toolbox and run decidim-releaser

Source: https://github.com/decidim/decidim/blob/develop/docs/modules/develop/pages/maintainers/releases.adoc

Install the decidim-maintainers_toolbox gem and run the releaser command. Requires the GitHub CLI (gh) locally. The --github-token is obtained from gh auth token and --version-type is set to patch.

```bash
gem install decidim-maintainers_toolbox
decidim-releaser --github-token=$(gh auth token) --version-type=patch
```

--------------------------------

### CreateBudget variables example

Source: https://github.com/decidim/decidim/blob/develop/docs/modules/develop/pages/api/reference/components/budgets/create.adoc

Example variables for the CreateBudget mutation. Shows the componentId and input attributes with totalBudget and an English title.

```json
{
  "componentId": "3",
  "input": {
    "attributes": {
      "totalBudget": 1234,
      "title": {
        "en": "Budget created from API"
      }
    }
  }
}
```

--------------------------------

### Example variables for closeDebate

Source: https://github.com/decidim/decidim/blob/develop/docs/modules/develop/pages/api/reference/components/debates/close.adoc

Example JSON variables to submit with the closeDebate mutation. The input includes the locale and the conclusions text.

```json
{
  "componentId": "9",
  "debateId": "2",
  "input": {
    "locale": "en",
    "attributes": {
      "conclusions": "Your closing report"
    }
  }
}
```

--------------------------------

### Install decidim-maintainers_toolbox and run releaser

Source: https://github.com/decidim/decidim/blob/develop/docs/modules/develop/pages/maintainers/releases.adoc

Install the latest version of the decidim-maintainers_toolbox gem and run the releaser command with a GitHub token. Requires the gh CLI locally.

```bash
gem install decidim-maintainers_toolbox
decidim-releaser --github-token=$(gh auth token) --version-type=minor
```

--------------------------------

### Install PostgreSQL and create the decidim_app user

Source: https://github.com/decidim/decidim/blob/develop/docs/modules/install/pages/manual.adoc

Installs PostgreSQL and creates a database user named 'decidim_app' with the password 'thepassword'. The user has SUPERUSER and CREATEDB privileges but no CREATEROLE. Change the password and save it for later configuration.

```bash
sudo apt install -y postgresql libpq-dev
sudo -u postgres psql -c "CREATE USER decidim_app WITH SUPERUSER CREATEDB NOCREATEROLE PASSWORD 'thepassword'"
```

--------------------------------

### API change example: before and after

Source: https://github.com/decidim/decidim/blob/develop/RELEASE_NOTES.md

Example showing how to update code when an API changes. The first block shows the old usage, the second shows the new usage. Replace the old code with the new code.

```ruby
# Explain the usage of the API as it was in the previous version
result = 1 + 1 if before
```

```ruby
# Explain the usage of the API as it is in the new version
result = 1 + 1 if after
```

--------------------------------

### Example geocoding builder_options configuration

Source: https://github.com/decidim/decidim/blob/develop/docs/modules/develop/pages/maps.adoc

Example configuration object returned by the builder's builder_options method. This configuration is passed to the front-end and available via the data-decidim-geocoding attribute.

```js
{ url: "https://photon.example.org/api/", other_config: "foo" }
```

--------------------------------

### Existing taxonomies example

Source: https://github.com/decidim/decidim/blob/develop/docs/modules/develop/pages/taxonomies.adoc

Example of the existing_taxonomies object, which contains the tree structure of existing taxonomies for reference only and is not used in the import process.

```json
"existing_taxonomies": {
  "Scopes": {
    "Scope 1": {
      "Scope 1.1": {},
      "Scope 1.2": {}
    },
    "Scope 2": {}
  },
  "Another taxonomization": {
    "Another item": {}
  }
  ...
}
```

--------------------------------

### Install rbenv-vars plugin

Source: https://github.com/decidim/decidim/blob/develop/docs/modules/install/pages/manual.adoc

Installs the rbenv-vars plugin to manage environment variables for the Decidim application. Ensure rbenv is initialized.

```bash
git clone https://github.com/rbenv/rbenv-vars.git "$(rbenv root)"/plugins/rbenv-vars
```

--------------------------------

### Decidim initializer file format

Source: https://github.com/decidim/decidim/blob/develop/docs/modules/configure/pages/initializer.adoc

Starts a new Decidim initializer file. Use this as the base for adding any configuration keys listed below.

```ruby
# config/initializer/decidim.rb
Decidim.configure do |config|
  # here you can add any key config from below.
end
```

--------------------------------

### Start Puma manually with SSL

Source: https://github.com/decidim/decidim/blob/develop/docs/modules/develop/pages/guide_development_with_localhost_ssl.adoc

Starts Puma in SSL mode using the generated certificate. This disables non-SSL access on port 3000. The server is accessible at https://localhost:3443/.

```bash
bin/rails s -b "ssl://127.0.0.1:3443?key=$HOME/certs/localhost.key&cert=$HOME/certs/localhost.crt"
```

--------------------------------

### Use the content parser class

Source: https://github.com/decidim/decidim/blob/develop/docs/modules/develop/pages/content_processors.adoc

Shows how to use the content parser class. Instantiate the parser with the content and an empty options hash, then call rewrite to get the rewritten content and metadata to get the Metadata object.

```ruby
parser = Decidim::ContentParsers::SpecialWordsParser.new(content, {})
parser.rewrite # returns the content rewritten
parser.metadata # returns a Metadata object
```

--------------------------------

### Create development app

Source: https://github.com/decidim/decidim/blob/develop/docs/modules/develop/pages/guide_development_app.adoc

Clones the Decidim repository, installs dependencies, and creates the development app. The generated development_app/ directory is gitignored.

```console
git clone https://github.com/decidim/decidim.git
cd decidim
bundle install
bin/rake development_app
```

--------------------------------

### MyTimestampService class example

Source: https://github.com/decidim/decidim/blob/develop/docs/modules/services/pages/timestamp.adoc

Two example implementations of a timestamp service class. The first returns a placeholder string, while the second leaves the timestamp method empty for actual implementation. Both initialize with a hash containing the :document key.

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

```ruby
class MyTimestampService
  attr_accessor :document

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

  def timestamp
    # Actual code to add the timestamp
  end
end
```

--------------------------------

### Example variables for CreateMeeting mutation

Source: https://github.com/decidim/decidim/blob/develop/docs/modules/develop/pages/api/reference/components/meetings/create.adoc

Example JSON variables to submit with the CreateMeeting mutation. Includes componentId and input attributes with sample values for a meeting.

```json
{
  "componentId": 670,
  "input": {
    "locale": "en",
    "attributes": {
      "address": "Carrer de la Pau, 1, Barcelona",
      "availableSlots": 10,
      "description": "Cities need more people, not more cars",
      "endTime": "2025-12-24T22:10:22Z",
      "iframeAccessLevel": "ALL",
      "iframeEmbedType": "NONE",
      "latitude": 40.1234,
      "location": "Somewhere",
      "locationHints": "Near the main square",
      "longitude": 2.1234,
      "onlineMeetingUrl": "https://meets.example.org/abc-def",
      "registrationTerms": "By registering you agree to the terms and conditions",
      "registrationType": "ON_THIS_PLATFORM",
      "registrationUrl": "https://example.org/register",
      "registrationsEnabled": true,
      "startTime": "2025-12-24T20:10:22Z",
      "taxonomies": [1072],
      "title": "More sidewalks and less roads",
      "typeOfMeeting": "ONLINE"
    }
  }
}
```

--------------------------------

### Install Decidim gem and system dependencies

Source: https://github.com/decidim/decidim/blob/develop/docs/modules/install/pages/manual.adoc

Installs system dependencies for Decidim (libicu-dev, ImageMagick, libvips, and libvips-tools) and the decidim gem. Requires sudo and RubyGems compatibility.

```bash
sudo apt install -y libicu-dev imagemagick libvips libvips-tools
gem install decidim
```

--------------------------------

### Install decidim-elections with Bundler and Rails

Source: https://github.com/decidim/decidim/blob/develop/decidim-elections/README.md

Install the decidim-elections module. Requires Decidim 0.31 or later. Run these commands in your console to add the gem, upgrade the application, and migrate the database.

```bash
bundle add decidim-elections
bundle exec rails decidim:upgrade
bundle exec rails db:migrate

```

--------------------------------

### Example of decidim_participatory_process_types configuration

Source: https://github.com/decidim/decidim/blob/develop/docs/modules/develop/pages/taxonomies.adoc

Example of the `decidim_participatory_process_types` section in a participatory space configuration. It defines two taxonomies (`omnis` and `debitis`) with their names and resources, and a filter that is a space filter for the `participatory_processes` manifest, with items referencing the taxonomies and an empty components array.

```json
"decidim_participatory_process_types": {
  "~ Participatory process types": {
    "taxonomies": {
      "omnis": {
        "name": {
          "ca": "explicabo",
          "en": "omnis",
          "machine_translations": {
            "es": "quia"
          }
        },
        "children": {},
        "resources": {
          "gid://decidim-development-app/Decidim::ParticipatoryProcess/2": "Architecto vitae dolor minima iure."
        }
      },
      "debitis": {
        "name": {
          "ca": "qui",
          "en": "debitis",
          "machine_translations": {
            "es": "et"
          }
        },
        "children": {
        },
        "resources": {
          "gid://decidim-development-app/Decidim::ParticipatoryProcess/1": "Process with no scopes"
        }
      }
    },
    "filters": [
      {
        "name": "~ Participatory process types",
        "space_filter": true,
        "space_manifest": "participatory_processes",
        "items": [
          ["omnis"],
          ["debitis"]
        ],
        "components": []
      }
    ]
  }
}
```

--------------------------------

### Start development server with SSL

Source: https://github.com/decidim/decidim/blob/develop/docs/modules/develop/pages/guide_development_with_localhost_ssl.adoc

Starts the Rails development server with SSL enabled on port 3443. Requires the decidim-dev gem in the :development group of the Gemfile. The server also runs on port 3000 for non-SSL access.

```bash
DEV_SSL=true bin/rails s
```

--------------------------------

### Bullet N+1 query log example

Source: https://github.com/decidim/decidim/blob/develop/docs/modules/develop/pages/profiling.adoc

Example log entry from Bullet when it detects an N+1 query. It suggests adding .includes([:author]) to the query and also warns about unnecessary eager loads.

```bash
user: xxx
GET /
USE eager loading detected
  Decidim::Comments::Comment => [:author]
  Add to your query: .includes([:author])
Call stack
```

--------------------------------

### Example submitted variables for updateProject

Source: https://github.com/decidim/decidim/blob/develop/docs/modules/develop/pages/api/reference/components/budgets/projects/update.adoc

Example variables submitted with the updateProject mutation. Shows the required componentId, budgetId, and input object with the project id and attributes to update, including budgetAmount, address, latitude, longitude, proposalIds, taxonomies, description, and title.

```json
{
  "componentId": "3",
  "budgetId": "5",
  "input": {
    "id": "5",
    "attributes": {
      "budgetAmount": 12300,
      "address": "FOOBAR",
      "latitude": 123,
      "longitude": 12.33,
      "proposalIds": [ 1, 2, 3],
      "taxonomies": [ 1, 2, 3],
      "description": {
        "en": "Project description changed from API"
      },
      "title": {
        "en": "Project title changed from API"
      }
    }
  }
}
```

--------------------------------

### Accessible page shared example for system specs

Source: https://github.com/decidim/decidim/blob/develop/docs/modules/develop/pages/guide_accessibility.adoc

Add this shared example to system specs to verify the page passes technical accessibility evaluation and contains valid HTML. It helps maintain accessibility across changes.

```ruby
it_behaves_like "accessible page"

```

--------------------------------

### Run system specs in parallel

Source: https://github.com/decidim/decidim/blob/develop/docs/modules/develop/pages/testing.adoc

Runs all system specs from a module in parallel using the parallel_tests gem. This example runs the system specs for decidim-participatory_processes.

```bash
cd decidim-participatory_processes
bundle exec rake parallel:spec[spec/system/]
```

--------------------------------

### MyPDFSignatureService

Source: https://github.com/decidim/decidim/blob/develop/docs/modules/services/pages/pdf.adoc

Example class showing how to implement a PDF signature service. The class is initialized with a hash containing the :pdf key and responds to a signed_pdf method.

```APIDOC
## MyPDFSignatureService

### Description
Processes a PDF and returns the document including a digital signature. The instance is initialized with a hash containing the :pdf key with the PDF file content as value, and responds to a signed_pdf method containing the PDF with the signature.

### Method
initialize

### Parameters
#### Arguments
- **pdf** (required) - The document that needs to be signed

### Request Example
```ruby
MyPDFSignatureService.new(pdf: pdf_content)
```

### Response
#### Success Response
Returns an instance of MyPDFSignatureService with the pdf attribute set.

### signed_pdf

### Description
Returns the PDF with the digital signature applied.

### Method
signed_pdf

### Response
#### Success Response
Returns the signed PDF content.
```

--------------------------------

### Set up empty Decidim database: db:create, decidim_system:create_admin, and rails s

Source: https://github.com/decidim/decidim/blob/develop/docs/modules/install/pages/empty-database.adoc

Run these commands in sequence from the root of your project to set up an empty Decidim database, create a system admin account, and start the Rails server. The first command creates the database and runs migrations. The second command prompts for system admin credentials; for documentation conformity, use email system@example.org and password decidim123456789, though this is not secure for production. The third command starts the server so you can configure the organization from the system panel.

```bash
bin/rails db:create db:migrate
```

```bash
bin/rails decidim_system:create_admin
```

```bash
bundle exec rails s
```

--------------------------------

### Handle geocoder-suggest.decidim event with AJAX

Source: https://github.com/decidim/decidim/blob/develop/docs/modules/develop/pages/maps.adoc

Complete example of handling the geocoder-suggest.decidim event. The callback expects an array of result objects with key, value, and optionally coordinates keys. The example uses a GET request to the configured URL and maps the response suggestions.

```js
$(document).on("ready", () => {
  $("[data-decidim-geocoding]").each((_i, el) => {
    const $input = $(el);
    const config = $input.data("decidim-geocoding");

    $input.on("geocoder-suggest.decidim", (event, query, callback) => {
        currentSuggestionQuery = setTimeout(() => {
          $.ajax({
            method: "GET",
            url: config.url,
            data: { apiKey: config.apiKey },
            dataType: "json"
          }).done((resp) => {
            if (resp.suggestions) {
              return callback(resp.suggestions.map((item) => {
                return {
                  key: item.label,
                  value: item.label,
                  coordinates: [item.latitude, item.longitude],
                  yourExtraData: item.yourExtraData
                }
              }));
            }
            return null;
          });
    });
  });
});
```

--------------------------------

### Set up and boot the development_app

Source: https://github.com/decidim/decidim/blob/develop/docs/modules/develop/pages/profiling.adoc

Run these commands in the decidim root folder to set up and boot the development_app with profiling gems. The first command creates the app, then you move into it and start the Rails server.

```bash
bundle exec rake development_app
```

```bash
cd development_app
bundle exec rails s
```

--------------------------------

### Define a reminder generator for meetings

Source: https://github.com/decidim/decidim/blob/develop/docs/modules/develop/pages/reminders.adoc

Example reminder generator class for upcoming meetings. It queries meetings starting within a configurable number of days, creates or updates reminder records for registrations, and queues a job to send notifications. The `before_days` setting is read from the reminder manifest.

```ruby
# frozen_string_literal: true

module Decidim
  module Meetings
    # This class is the generator class which creates and updates meeting related reminders,
    # after reminder is generated it is send to user who are participating to upcoming meetings.
    class MeetingReminderGenerator
      attr_reader :reminder_jobs_queued

      def initialize
        @reminder_manifest = Decidim.reminders_registry.for(:meetings)
        @reminder_jobs_queued = 0
        @queued_reminders = []
      end

      # Creates reminders and updates them if they already exists.
      def generate
        Decidim::Component.where(manifest_name: "meetings").each do |component|
          send_reminders(component)
        end
      end

      # This can be called by the admin command that manually triggers the reminders.
      def generate_for(component)
        send_reminders(component)
      end

      private

      attr_reader :reminder_manifest, :queued_reminders

      def send_reminders(component)
        # before_days could be provided as a configuration option, e.g. `2.days`
        before_days = reminder_manifest.settings.attributes[:before_days]
        Decidim::Meetings::Meeting.where(component: component).where(
          "start_time >= ? AND start_time <= ?",
          DateTime.now + before_days.days
          DateTime.now + before_days.days + 1.day
        ).each do |meeting|
          Decidim::Meetings::Registration.where(meeting: meeting).each do |registration|
            reminder = Decidim::Reminder.find_or_create_by(user: registration.user, component: component)
            record = Decidim::ReminderRecord.find_or_create_by(reminder: reminder, remindable: meeting)
            record.update(state: "active") unless record.active?
            reminder.records << record
            reminder.save!
            next if queued_reminders.include?(reminder.id)

            Decidim::Meetings::SendMeetingRemindersJob.perform_later(reminder)
            @reminder_jobs_queued += 1
            queued_reminders << reminder.id
          end
        end
      end
    end
  end
end
```

--------------------------------

### CreateProposal sample variables

Source: https://github.com/decidim/decidim/blob/develop/docs/modules/develop/pages/api/reference/components/proposals/create.adoc

Example JSON variables for the CreateProposal mutation, including componentId and input attributes with title, body, address, latitude, and longitude.

```json
{
  "componentId": 9,
  "input": {
    "locale": "en",
    "attributes": {
      "title": "Install Bike Lanes on Main Street",
      "body": "We propose adding dedicated bike lanes along Main Street to improve cyclist safety and encourage sustainable transportation.",
      "address": "Main Street, Barcelona, Spain",
      "latitude": 41.3851,
      "longitude": 2.1734
    }
  }
}
```

--------------------------------

### Install Decidim gem

Source: https://github.com/decidim/decidim/blob/develop/docs/modules/configure/pages/index.adoc

Installs the Decidim gem via RubyGems.

```console
gem install decidim
```

--------------------------------

### Use the content renderer class

Source: https://github.com/decidim/decidim/blob/develop/docs/modules/develop/pages/content_processors.adoc

Shows how to use the content renderer class. Instantiate the renderer with the content and call render to get the formatted content.

```ruby
renderer = Decidim::ContentRenderers::SpecialWordsRenderer.new(content)
parser.render # returns the content formatted
```

--------------------------------

### Create dummy test application

Source: https://github.com/decidim/decidim/blob/develop/docs/modules/develop/pages/testing.adoc

Creates a dummy application required to run tests for Decidim engines. Run this command in the decidim root's folder before running any tests.

```bash
bundle exec rake test_app
```

--------------------------------

### Create taxonomy import plan

Source: https://github.com/decidim/decidim/blob/develop/docs/modules/develop/pages/taxonomies.adoc

Creates a JSON plan file in `tmp/taxonomies/` for each organization (e.g., `tmp/taxonomies/example.com_plan.json`). The command outputs the path of the created file(s).

```bash
bin/rails decidim:taxonomies:make_plan
```

--------------------------------

### Store certificate files in ~/certs

Source: https://github.com/decidim/decidim/blob/develop/docs/modules/develop/pages/guide_development_with_localhost_ssl.adoc

Creates a certs directory in the home folder and moves the generated certificate files there. The files are used later when starting the server manually.

```bash
mkdir ~/certs/
mv localhost.crt ~/certs/
mv localhost.key ~/certs/
```

--------------------------------

### UpdateResult variables example

Source: https://github.com/decidim/decidim/blob/develop/docs/modules/develop/pages/api/reference/components/accountability/update.adoc

Example variables for the updateResult mutation. Updates the English title of result 18 in component 1.

```json
{
  "componentId": "1",
  "resultId": "18",
  "input": {
    "attributes": {
      "title": {
        "en": "My Result Title - updated"
      }
    }
  }
}
```

--------------------------------

### Deploy Etherpad with Docker stack

Source: https://github.com/decidim/decidim/blob/develop/docs/modules/services/pages/etherpad.adoc

Initialize Docker swarm and deploy the Etherpad stack using the provided docker-compose-etherpad.yml file. Run 'docker swarm init' only once before deploying.

```sh
docker swarm init # just one time

docker stack deploy --compose-file docker-compose-etherpad.yml decidim-etherpad
```

--------------------------------

### Install decidim-maintainers_toolbox gem

Source: https://github.com/decidim/decidim/blob/develop/docs/modules/develop/pages/backports.adoc

Installs the decidim-maintainers_toolbox gem, which provides commands for day-to-day backport activities. Requires the gh command from GitHub to be available before use.

```bash
gem install decidim-maintainers_toolbox
```

--------------------------------

### Machine Translation Service Class Example

Source: https://github.com/decidim/decidim/blob/develop/docs/modules/configure/pages/initializer.adoc

Example class for a machine translation service. The translate method should contain the actual code to translate the text.

```ruby
class MyTranslationService
  attr_reader :text, :source_locale, :target_locale, :resource, :field_name

  def initialize(resource, field_name, text, target_locale, source_locale)
    @resource = resource
    @field_name = field_name
    @text = text
    @target_locale = target_locale
    @source_locale = source_locale
  end

  def translate
    # Actual code to translate the text
  end
end
```

--------------------------------

### Create a system admin with decidim_system:create_admin

Source: https://github.com/decidim/decidim/blob/develop/decidim-system/README.md

Run this command from your terminal to create a system admin account. You will be prompted for an email and password; the password is not displayed and must be confirmed.

```bash
bin/rails decidim_system:create_admin
```

--------------------------------

### Use custom Sidekiq configuration file

Source: https://github.com/decidim/decidim/blob/develop/RELEASE_NOTES.md

Use this command to call an additional configuration file for Sidekiq, preserving your custom queues or environment-specific settings that would otherwise be overwritten during the upgrade.

```bash
sidekiq -C config/sidekiq.yml -C config/sidekiq.local.yml
```

--------------------------------

### CreateProject error response example

Source: https://github.com/decidim/decidim/blob/develop/docs/modules/develop/pages/api/reference/components/budgets/projects/create.adoc

Example JSON error response for the CreateProject mutation. Shows an ATTRIBUTE_VALIDATION_ERROR with an empty message. To fix, check taxonomy parameters.

```json
{
  "errors": [
    {
      "message": [],
      "locations": [
        {
          "line": 5,
          "column": 8
        }
      ],
      "path": [
        "component",
        "budget",
        "createProject"
      ],
      "extensions": {
        "code": "ATTRIBUTE_VALIDATION_ERROR"
      }
    }
  ],
  "data": {
    "component": {
      "budget": {
        "createProject": null
      }
    }
  }
}
```

--------------------------------

### Install decidim-collaborative_texts with bundle and rails commands

Source: https://github.com/decidim/decidim/blob/develop/decidim-collaborative_texts/README.md

Run these commands in your console to install the module. Requires Decidim 0.31 or later. The module is under development and not ready for usage yet.

```bash
bundle add decidim-collaborative_texts
bundle exec rails decidim:upgrade
bundle exec rails db:migrate
```

--------------------------------

### Create initial Git commit for the Decidim app

Source: https://github.com/decidim/decidim/blob/develop/docs/modules/install/pages/manual.adoc

Initializes a Git repository and creates the initial commit for the generated Decidim application. Run from the application directory.

```bash
cd decidim_application
git add .
git commit -m "Initial commit. Generated with Decidim https://decidim.org"
```

--------------------------------

### Configure social share services with DECIDIM_SOCIAL_SHARE_SERVICES

Source: https://github.com/decidim/decidim/blob/develop/docs/modules/customize/pages/social_shares.adoc

Sets the social share services to enable. Service names are case-sensitive.

```console
DECIDIM_SOCIAL_SHARE_SERVICES="Facebook, X"
```

--------------------------------

### Configure Etherpad integration

Source: https://github.com/decidim/decidim/blob/develop/docs/modules/configure/pages/initializer.adoc

Configures Etherpad integration. Only needed if you want Etherpad integration with Decidim. See Etherpad's Decidim docs for setup.

```ruby
config.etherpad = {
  server: ENV["ETHERPAD_SERVER"],
  api_key: ENV["ETHERPAD_API_KEY"],
  api_version: Decidim::Env.new("ETHERPAD_API_VERSION", "1.2.1")
}
```

--------------------------------

### Organization object example

Source: https://github.com/decidim/decidim/blob/develop/docs/modules/develop/pages/taxonomies.adoc

Example of the organization object in the plan file. The locale field is the most important as it is used to translate taxonomy and filter names and to compare with existing taxonomies.

```json
"organization": {
  "id": 1,
  "name": "Example Organization",
  "host": "example.com",
  "locale": "en"
}
```

--------------------------------

### UpdateMeeting variables example

Source: https://github.com/decidim/decidim/blob/develop/docs/modules/develop/pages/api/reference/components/meetings/update.adoc

Example variables to submit with the UpdateMeeting mutation. Shows the structure of the input object with all attributes, including optional fields like iframeAccessLevel and iframeEmbedType.

```json
{
  "componentId": 670,
  "meetingId": "2",
  "input": {
    "locale": "en",
    "attributes": {
      "address": "Carrer de la Pau, 1, Barcelona",
      "availableSlots": 10,
      "description": "Cities need more people, not more cars",
      "endTime": "2025-12-24T22:10:22Z",
      "iframeAccessLevel": "ALL",
      "iframeEmbedType": "NONE",
      "latitude": 40.1234,
      "location": "Somewhere",
      "locationHints": "Near the main square",
      "longitude": 2.1234,
      "onlineMeetingUrl": "https://meets.example.org/abc-def",
      "registrationTerms": "By registering you agree to the terms and conditions",
      "registrationType": "ON_THIS_PLATFORM",
      "registrationUrl": "https://example.org/register",
      "registrationsEnabled": true,
      "startTime": "2025-12-24T20:10:22Z",
      "taxonomies": [1072],
      "title": "More sidewalks and less roads",
      "typeOfMeeting": "ONLINE"
    }
  }
}
```

--------------------------------

### Configure AI tools in config/initializers/decidim_ai.rb

Source: https://github.com/decidim/decidim/blob/develop/docs/modules/services/pages/aitools.adoc

Create this initializer file to configure the AI tools. It sets resource and user score thresholds, analyzers, detection services, and models. The example shows default values and commented alternatives.

```ruby
Decidim::Ai::SpamDetection.resource_score_threshold = 0.75 # default
# The entry must be a hash with the following keys:
# - name: the name of the analyzer
# - strategy: the class of the strategy to use
# - options: a hash with the options to pass to the strategy
# Example:
# Decidim::Ai.registered_analyzers = [
#   {
#     name: :bayes,
#     strategy: Decidim::Ai::SpamContent::BayesStrategy,
#     options: {
#       adapter: :redis,
#       params: {
#         url:                lambda { ENV["REDIS_URL"] }
#       }
#     }
#   }
# ]
Decidim::Ai::SpamDetection.resource_analyzers = [
  {
    name: :bayes,
    strategy: Decidim::Ai::SpamDetection::Strategy::Bayes,
    options: {
      adapter: ENV.fetch("DECIDIM_SPAM_DETECTION_BACKEND_RESOURCE", "redis"),
      params: { url: ENV.fetch("DECIDIM_SPAM_DETECTION_BACKEND_RESOURCE_REDIS_URL", "redis://localhost:6379/2") }
    }
  }
]

Decidim::Ai::SpamDetection.reporting_user_email = "your-admin@example.org"

# If you want to use a different spam detection service,
# you can use a class service having the following contract
#
Decidim::Ai::SpamDetection.resource_detection_service = "Decidim::Ai::SpamDetection::Service"

# Customize here what are the analyzed models. You may want to use this to
# override what we register by default, or to register your own resources.

Decidim::Ai::SpamDetection.resource_models = {
  "Decidim::Comments::Comment" => "Decidim::Ai::SpamDetection::Resource::Comment",
  "Decidim::Initiative" => "Decidim::Ai::SpamDetection::Resource::Initiative",
  "Decidim::Debates::Debate" => "Decidim::Ai::SpamDetection::Resource::Debate",
  "Decidim::Meetings::Meeting" => "Decidim::Ai::SpamDetection::Resource::Meeting",
  "Decidim::Proposals::Proposal" => "Decidim::Ai::SpamDetection::Resource::Proposal",
  "Decidim::User" => "Decidim::Ai::SpamDetection::Resource::UserBaseEntity"
}

Decidim::Ai::SpamDetection.user_score_threshold = 0.75 # default

# The entry must be a hash with the following keys:
# - name: the name of the analyzer
# - strategy: the class of the strategy to use
# - options: a hash with the options to pass to the strategy
# Example:
# Decidim::Ai::SpamDetection.user_analyzers = [
#   {
#     name: :bayes,
#     strategy: Decidim::Ai::SpamContent::BayesStrategy,
#     options: {
#       adapter: :redis,
#       params: {
#         url:                lambda { ENV["REDIS_URL"] }
#       }
#     }
#   }
# ]
Decidim::Ai::SpamDetection.user_analyzers = [
  {
    name: :bayes,
    strategy: Decidim::Ai::SpamDetection::Strategy::Bayes,
    options: {
      adapter: ENV.fetch("DECIDIM_SPAM_DETECTION_BACKEND_USER", "redis"),
      params: { url: ENV.fetch("DECIDIM_SPAM_DETECTION_BACKEND_USER_REDIS_URL", "redis://localhost:6379/3") }
    }
  }
]

# Customize here what are the analyzed models. You may want to use this to
# override what we register by default, or to register your own resources.
# Follow the documentation on how to trail more resources
Decidim::Ai::SpamDetection.user_models = {
  "Decidim::User" => "Decidim::Ai::SpamDetection::Resource::UserBaseEntity"
}

# If you want to use a different spam detection service, you can define your own service.
# Refer to documentation for more details.
#
Decidim::Ai::SpamDetection.user_detection_service = "Decidim::Ai::SpamDetection::Service"
```

--------------------------------

### Example YAML translations for statistics category

Source: https://github.com/decidim/decidim/blob/develop/docs/modules/customize/pages/data_consent.adoc

Example English translations for the new category and its cookie item. The description explains the purpose, and the service names the third-party service.

```yaml
en:
  layouts:
    decidim:
      data_consent:
        modal:
          statistics:
            title: The title for the statistics
            description: The description for the statistics
        details:
          items:
            statistics-cookie:
              description: The purpose of the cookie
              service: The 3rd party service of the cookie
```

--------------------------------

### Define component imports with creator, messages, and example data

Source: https://github.com/decidim/decidim/blob/develop/docs/modules/develop/pages/components.adoc

Configures the import functionality for a component, including supported formats (CSV, JSON, Excel), a custom creator class, UI messages, and an example data set for download. The example data uses the component's organization locales to generate title and body columns.

```ruby
component.imports :component_resources do |imports|
  # Define a form partial if you want to add custom fields to the form
  # imports.form_view = "decidim/my_component/admin/imports/component_resources_fields"
  # Define a custom form class name if you want to customize the form object
  # imports.form_class_name = "MyComponent::Admin::CustomImportForm"

  # Define UI messages for the import functionality
  imports.messages do |msg|
    # The resource name is used in the success message:
    # "X your resources successfully imported" (the "your resources" part)
    msg.set(:resource_name) { |count: 1| I18n.t("decidim.my_component.admin.imports.resources.component_resources", count: count) }
    # The title is the message shown at the top of the import page
    msg.set(:title) { I18n.t("decidim.my_component.admin.imports.title.component_resources") }
    # The label is what is shown in the import dropdown menu
    msg.set(:label) { I18n.t("decidim.my_component.admin.imports.label.component_resources") }
    # The optional help message can be used to provide additional contextual
    # help for the import file, e.g. how it should be formatted
    # msg.set(:help) { I18n.t("decidim.my_component.admin.imports.help.component_resources") }
  end

  # Define the creator that is used to create resources from the import data
  imports.creator MyComponent::ResourceCreator

  # Define an example data set to guide the user how to format the import
  # file. This will be available for download in the import view for each
  # supported import format.
  imports.example do |import_component|
    organization = import_component.organization
    [
      organization.available_locales.map { |l| "title/#{l}" } + organization.available_locales.map { |l| "body/#{l}" },
      organization.available_locales.map { "Example title" } + organization.available_locales.map { "Example body" },
      organization.available_locales.map { "Example title 2" } + organization.available_locales.map { "Example body 2" },
    ]
  end
end
```

--------------------------------

### Admin Controller with Forms, Commands, Queries, and Permissions

Source: https://github.com/decidim/decidim/blob/develop/docs/modules/develop/pages/classes/controllers.adoc

Illustrates Decidim admin controller conventions, including the use of ResourceForm, CreateMyResource and UpdateMyResource commands, a query (Decidim::MyModule::MyQuery), and enforce_permission_to. The controller handles index, new, create, edit, and update actions with flash messages and redirects.

```ruby
# frozen_string_literal: true

# app/controllers/decidim/my_module/admin/resources_controller.rb
module Decidim
  module MyModule
    module Admin
      class ResourcesController < Decidim::MyModule::Admin::ApplicationController
        def index
          enforce_permission_to :read, :resource
          @resources = paginate(resources)
        end

        def new
          enforce_permission_to :create, :resource
          @form = form(ResourceForm).from_params(params)
        end

        def create
          enforce_permission_to :create, :resource
          @form = form(ResourceForm).from_params(params)

          CreateMyResource.call(@form) do
            on(:ok) do
              flash[:notice] = I18n.t("resource.create.success", scope: "decidim.my_module.admin")
              redirect_to action: :index
            end

            on(:invalid) do
              flash.now[:alert] = I18n.t("resource.create.invalid", scope: "decidim.my_module.admin")
              render action: :new
            end
          end
        end

        def edit
          enforce_permission_to :update, :resource, resource: resource
          @form = form(ResourceForm).from_model(resource)
        end

        def update
          enforce_permission_to :update, :resource, resource: resource
          @form = form(ResourceForm).from_params(params)

          UpdateMyResource.call(@form) do
            on(:ok) do
              flash[:notice] = I18n.t("resource.update.success", scope: "decidim.my_module.admin")
              redirect_to action: :index
            end

            on(:invalid) do
              flash.now[:alert] = I18n.t("resource.update.invalid", scope: "decidim.my_module.admin")
              render action: :edit
            end
          end
        end

        private
        def resources
          @resources ||= Decidim::MyModule::MyQuery.for([current_component])
        end

        def resource
          resources.find(params[:id])
        end
      end
    end
  end
end

```

--------------------------------

### Add rails-footnotes gem to Gemfile

Source: https://github.com/decidim/decidim/blob/develop/docs/modules/customize/pages/gemfile.adoc

Adds the rails-footnotes gem with version constraint '~> 4.0' to the Gemfile. After adding, run bundle install and follow any gem-specific installation steps.

```ruby
gem 'rails-footnotes', '~> 4.0'
```

--------------------------------

### Create .rbenv-vars with database credentials

Source: https://github.com/decidim/decidim/blob/develop/docs/modules/install/pages/manual.adoc

Creates a .rbenv-vars file with database connection variables (host 'localhost', user 'decidim_app', password 'thepassword'). Place the file in any folder above the Decidim application, not inside it to avoid exposing secrets. Use the actual password from the PostgreSQL setup.

```bash
cat << EOF > .rbenv-vars
DATABASE_HOST=localhost
DATABASE_USERNAME=decidim_app
DATABASE_PASSWORD=thepassword
EOF
```

--------------------------------

### UpdateProposal variables example

Source: https://github.com/decidim/decidim/blob/develop/docs/modules/develop/pages/api/reference/components/proposals/update.adoc

Example variables for the updateProposal mutation. Shows the structure of the input object with locale, attributes, and optional fields like address, latitude, longitude, and taxonomies.

```json
{
  "componentId": 9,
  "proposalId": "140",
  "input": {
    "locale": "en",
    "attributes": {
      "title": "Install Bike Lanes on Main Street",
      "body": "We propose adding dedicated bike lanes along Main Street to improve cyclist safety and encourage sustainable transportation.",
      "address": "Main Street, Barcelona, Spain",
      "latitude": 41.3851,
      "longitude": 2.1734,
      "taxonomies": [123, 456]
    }
  }
}
```

--------------------------------

### Generated static map URL with custom options

Source: https://github.com/decidim/decidim/blob/develop/docs/modules/develop/pages/maps.adoc

Example URL generated by the `url` method with latitude `1.123`, longitude `2.456`, and the custom configuration options (`style=bright`, `foo=bar`). Shows the default query parameters (`zoom=15`, `width=300`, `height=300`) combined with the custom ones.

```bash
https://staticmap.example.org/?latitude=1.123&longitude=2.456&zoom=15&width=300&height=300&style=bright&foo=bar
```

--------------------------------

### ResourceForm class example

Source: https://github.com/decidim/decidim/blob/develop/docs/modules/develop/pages/classes/forms.adoc

Example of a Decidim form class with translatable attributes and validations. Place it in app/forms/decidim/my_module/resource_form.rb. Includes a custom validation that adds an error if title equals 'invalid'.

```ruby
# frozen_string_literal: true

# app/forms/decidim/my_module/resource_form.rb
module Decidim
  module MyModule
    class ResourceForm < Decidim::Form
      include Decidim::TranslatableAttributes

      attribute :title, String
      translatable_attribute :body, String

      validates :title, length: { maximum: 150 }, translatable_presence: true
      validates :body, translatable_presence: true

      validate :some_custom_validation

      private

      def some_custom_validation
        errors.add(:title, :invalid) if title == "invalid"
      end
    end
  end
end
```

--------------------------------

### Scheduled task example with crontab

Source: https://github.com/decidim/decidim/blob/develop/RELEASE_NOTES.md

Example crontab entry to run a Decidim task in production. Place this in your crontab configuration to schedule the task. Adjust the path and environment as needed.

```bash
4 0 * * * cd /home/user/decidim_application && RAILS_ENV=production bundle exec rails decidim:TASK
```

--------------------------------

### Run decidim-releaser for a Release Candidate

Source: https://github.com/decidim/decidim/blob/develop/docs/modules/develop/pages/maintainers/releases.adoc

Install the latest version of the decidim-maintainers_toolbox gem and run the releaser command for a Release Candidate version. Requires the gh CLI to be installed and authenticated locally.

```bash
gem install decidim-maintainers_toolbox
decidim-releaser --github-token=$(gh auth token) --version-type=rc
```

--------------------------------

### Download GPG key with gpg --keyserver

Source: https://github.com/decidim/decidim/blob/develop/SECURITY.md

Command to download the project's GPG key from pgp.mit.edu using the key ID 84B935C4. Recommended for secure communications.

```bash
gpg --keyserver pgp.mit.edu --recv 84B935C4
```