decidim 0.20.1 → 0.23.1

data/docs/customization/views.md

@@ -1,5 +1,34 @@
 # Views (HTML)
 
-If you want to add a new HTML page, you can do this by working as a regular Rails application.
+As usual you should make some tests with the changes that you made and configure a Continuous Integration environment for checking that your overrides doesn't get removed with new decidim versions.
 
-If you want to override a view or partial given by Decidim you can do this just by naming it with the same filename that you already have.
+## Overrides
+
+To find what you need to change you'll need to make some detective work to find out which partial or view do you need to change. You can do so by:
+
+- looking at your application log and finding the lines that start with "Rendered"
+- inspecting with the web development tools of your browser, copying a special class and using `grep`, github search or your IDE search by multiple files to find out on which file this exists.
+
+### Filename method
+
+If you want to override a view or partial given by Decidim you can do this just by naming it with the same filename that you already have. On more details, if you want to change the social media icons on the footer, you can do so by looking at which file you need to change, copying that file to your application with the same filename and directory structure, and making your local changes.
+
+As an example, if I want to change the footer, you'd need to search for the file (on this case, it's on [`decidim-core/app/views/layouts/decidim/_mini_footer.html.erb`](https://github.com/decidim/decidim/blob/e181d7e67bdf915a3a8e58416c683f52346de047/decidim-core/app/views/layouts/decidim/_mini_footer.html.erb)), and copy that file to your own application on `app/views/layouts/decidim/_mini_footer.html.erb`).
+
+## Deface method
+
+You'll need the [`deface` gem](https://github.com/spree/deface) installed on your application, and follow their instructions on how to use the different overridign methods that they support.
+
+As an example, if you want to change the footer, you can do so by creating the file `app/overrides/layouts/decidim/_main_footer/pre_footer.html.erb.deface` with these contents:
+
+```html
+<!-- insert_before ".main-footer" -->
+hello world
+```
+
+## New pages
+
+If you want to add a new HTML page, you can do this by working as a regular Rails application (ie, you can scaffold a new view and work with the HTML as usual).
+
+As an example of how to do this on Decidim Barcelona application, there's the [StaticController](
+https://github.com/AjuntamentdeBarcelona/decidim-barcelona/blob/d47d4a9ae6be26a0c5c4000907dda3c195579636/app/controllers/static_controller.rb) (main accountability section pages). You should inherit your controller from Decidim::ApplicationController.

data/docs/development_guide.md

@@ -30,6 +30,55 @@ Once created you are ready to:
 
 - `bin/rails s`
 
+## GitFlow Branching model
+
+The Decidim respository follows the GitFlow branching model. There are good documentations on it at:
+
+- the original post: https://nvie.com/posts/a-successful-git-branching-model/
+- provided by Atlassian: https://www.atlassian.com/git/tutorials/comparing-workflows/gitflow-workflow.
+
+This model introduces the `develop` branch as a kind of queue for new features to enter into the next release.
+
+In summary, Decidim developers that work on `feature/...` or `fix/...` branches will branch off from `develop` and must be merged back into `develop`.
+
+Then, to start a new feature branch off from `develop` in the following way:
+
+```bash
+git checkout develop
+git checkout -b feature/xxx
+```
+
+Implement the feature, and open a Pull Request as normal, but against `develop` branch. As this is the most common operation, `develop` is the default branch instead of `master`.
+
+### Naming Decidim branches
+
+We would like to have all branches following this namings:
+
+| Branch prefix | Comment |
+| --------  | -------- |
+| chore/    | Internal work. For instance, automatisms, etc. No production code change.     |
+| ci/       | For continous integration related tasks. No production code change.     |
+| deps/     | For dependency management tasks. |
+| doc/      | For changes to the documentation. |
+| feature/  | For new features for the users or for the Decidim command.  |
+| fix/      | For feature bugfixing. |
+| release/  | With MAYOR.MINOR-stable. For instance, release/0.22-stable |
+| refactor/ | For refactorings related with production code. |
+| test/     | When adding missing tests, refactoring tests, improving coverage, etc. |
+| backport/ | We only offer support for the last mayor version.  |
+
+## Git commit messages and Pull Request titles
+
+We recommend following [this guide](https://chris.beams.io/posts/git-commit/) for making good git commit messages. It also applies to Pull Request titles. The summary is:
+
+1. Separate subject from body with a blank line
+1. Limit the subject line to 50 characters
+1. Capitalize the subject line
+1. Do not end the subject line with a period
+1. Use the imperative mood in the subject line
+1. Wrap the body at 72 characters
+1. Use the body to explain what and why vs. how
+
 ## During development
 
 When creating new migrations in Decidim's modules, you will need to "apply" this migrations to your development_app. The way to do this is by copying the migration from your module into the db/migrate dir of your development_app. Luckily we already have a script that automates this: it copies all missing migrations in development_app/db/migrate. The command is:
@@ -38,6 +87,8 @@ When creating new migrations in Decidim's modules, you will need to "apply" this
 bin/rails decidim:upgrade
 ```
 
+Anyway we recommend re-creating your development_app every once in a while.
+
 ## Useful commands
 
 ### erb-lint
@@ -63,11 +114,12 @@ bundle exec i18n-tasks normalize --locales en
 
 ### JavaScript linter
 
-We use JavaScript's lint library to ensure homogeneous formatting of JavaScrip code.
+[eslint](https://eslint.org/docs/user-guide/command-line-interface) and [tslint](https://palantir.github.io/tslint/) are used to ensure homogeneous formatting of JavaScript code.
+
+To lint and try to fix linting errors, run:
 
 ```console
-yarn install
-yarn run lint --fix
+npm run lint --fix
 ```
 
 ### Stylelinter
@@ -112,43 +164,3 @@ This project uses [markdownlint](https://github.com/markdownlint/markdownlint) t
 ## Testing
 
 Refer to the [testing](advanced/testing.md) guide.
-
-## Releasing new versions
-
-In order to release new version you need to be owner of all the gems at RubyGems, ask one of the owners to add you before releasing. (Try `gem owners decidim`).
-
-Releasing new ***patch versions*** is quite easy, it's the same process whether it's a new version or a patch:
-
-1. Checkout the branch you want to release: `git checkout -b VERSION-stable`
-1. Update `.decidim-version` to the new version number.
-1. Run `bin/rake update_versions`, this will update all references to the new version.
-1. Run `bin/rake bundle`, this will update all the `Gemfile.lock` files
-1. Run `bin/rake webpack`, this will update the JavaScript bundle.
-1. Update `CHANGELOG.MD`. At the top you should have an `Unreleased` header with the `Added`, `Changed`, `Fixed` and `Removed` empty section. After that, the header with the current version and link.
-1. Commit all the changes: `git add . && git commit -m "Prepare VERSION release"`
-1. Run `bin/rake release_all`, this will create all the tags, push the commits and tags and release the gems to RubyGems.
-1. Once all the gems are published you should create a new release at this repository, just go to the [releases page](https://github.com/decidim/decidim/releases) and create a new one.
-1. Finally, you should update our [Docker repository](https://github.com/decidim/docker) so new images are build for the new release. To do it, just update `DECIDIM_VERSION` at [circle.yml](https://github.com/decidim/docker/blob/master/circle.yml).
-
-If this was a **major version** release:
-
-1. Go back to master with `git checkout master`
-1. Update `.decidim-version` to the new major development version
-1. Run `bin/rake update_versions`, this will update all references to the new version.
-1. Run `bin/rake bundle`, this will update all the `Gemfile.lock` files
-1. Run `bin/rake webpack`, this will update the JavaScript bundle.
-1. Update `SECURITY.md` and change the supported version to the new version.
-1. Commit all the changes: `git add . && git commit -m "Bump version" && git push origin master`
-1. Run `bin/rake release_all`, this will create all the tags, push the commits and tags and release the gems to RubyGems.
-1. Once all the gems are published you should create a new release at this repository, just go to the [releases page](https://github.com/decidim/decidim/releases) and create a new one.
-1. Finally, you should update our [Docker repository](https://github.com/decidim/docker) so new images are build for the new release. To do it, just update `DECIDIM_VERSION` at [circle.yml](https://github.com/decidim/docker/blob/master/circle.yml) and create the sibling branch at the Docker repository. NOTE: You should also take into account if the Ruby version has changed, in which case the Dockerfile should also be updated.
-
-To branch the stable version and let master be the new devel branch again:
-
-1. Create and push the stable branch from master: `git checkout master && git checkout -b VERSION-stable && git push origin VERSION-stable`
-1. Update the `CHANGELOG.MD`. At the top you should have an `Unreleased` header with the `Added`, `Changed`, `Fixed` and `Removed` empty section. After that, the header with the current version and link.
-1. Turn master into the dev branch for the next release:
-  1. Update `.decidim-version` to the new `dev` development version: x.y.z-dev
-  1. Run `bin/rake update_versions`, this will update all references to the new version.
-  1. Run `bin/rake bundle`, this will update all the `Gemfile.lock` files
-  1. Run `bin/rake webpack`, this will update the JavaScript bundle.

data/docs/getting_started.md

@@ -67,7 +67,7 @@ Then create a development application
 ```console
 d/bundle install
 d/rake development_app
-d/rails server
+d/rails server -b 0.0.0.0
 ```
 
 In general, to use the docker development environment, change any instruction in
@@ -103,8 +103,16 @@ Visit [http://localhost:3000](http://localhost:3000) to see your app running.
 
 Decidim comes pre-configured with some safe defaults, but can be changed through the `config/initializers/decidim.rb` file in your app. Check the comments there or read the comments in [the source file](https://github.com/decidim/decidim/blob/master/decidim-core/lib/decidim/core.rb) (the part with the `config_accessor` calls) for more up-to-date info.
 
-If you want to run the automatic rake task to delete data portability files, write in `crontab -e`
-`0 0 * * * cd /Users/you/projects/myrailsapp && /usr/local/bin/rake RAILS_ENV=production decidim:delete_data_portability_files`
+### Scheduled tasks
+
+For Decidim to function as expected, there are some background tasks that should be scheduled to be executed regularly.
+
+- Expired *data portability* files should be removed. To do it, write a `crontab -e` line like: `0 0 * * * cd /Users/you/projects/myrailsapp && /usr/local/bin/rake RAILS_ENV=production decidim:delete_data_portability_files`
+- *Metrics* also require a cron to be computed nightly. Find more information in the [related documentation](https://github.com/decidim/decidim/blob/master/docs/advanced/metrics.md#Configuration).
+- *Open Data* is also produced nightly via a scheduled job. Find more information in the [open-data documentation](https://github.com/decidim/decidim/blob/master/docs/advanced/open-data.md).
+- Registration forms for meetings that have ended should be removed for privacy concerns. To do it, write a `crontab -e` line like: `0 0 * * * cd /Users/you/projects/myrailsapp && /usr/local/bin/rake RAILS_ENV=production decidim_meetings:clean_registration_forms`
+
+### Further configuration
 
 We also have other guides on how to configure some extra components:
 
@@ -159,9 +167,11 @@ You can also make sure new translations are complete for all languages in your
 application with:
 
 ```console
-bin/rails decidim:check_locales
+TARGET_BRANCH=release/0.22-stable bin/rails decidim:check_locales
 ```
 
+Here the `TARGET_BRANCH` must be the same as the `decidim` dependency in your `Gemfile`.
+
 Be aware that this task might not be able to detect everything, so make sure you
 also manually check your application before upgrading.
 

data/docs/manual-installation.md

@@ -122,6 +122,10 @@ This data won't be created in production environments, if you still want to do i
 SEED=true rails db:setup
 ```
 
+#### Notes
+
+When you run `bin/rails db:migrate` you should see a lot of output. If you don't, or if you run into errors seeding your database, try runnning `bin/rake decidim:upgrade` before.
+
 You can now start your server!
 
 ```bash

data/docs/services/elections_bulletin_board.md

@@ -0,0 +1,38 @@
+# Elections Bulletin Board
+
+:warning: This is a work in progress and is not fully working yet.
+
+In order to celebrate [End-to-end auditable votings](https://en.wikipedia.org/wiki/End-to-end_auditable_voting_systems) using the Elections module, you will need to connect your Decidim instance with an instance of the [Decidim Bulletin Board application](https://github.com/decidim/decidim-bulletin-board/), preferably run by an independent organization.
+
+## Identification pair of keys generation
+
+The first step needed to setup the connection is to generate an a pair of keys to identify the application against the Bulletin Board. This can be done running the following rake task in your application environment:
+
+```sh
+bundle exec rake decidim_elections:generate_identification_keys
+```
+
+This task will output the generated private and public keys. You should copy the public key and send it to the Bulletin Board administrator through a secure channel. When copying the key, include the starting and ending lines with the prefix `-----`.
+
+After that, use one of these methods to make the private key available from your Decidim installation:
+
+a. Copy the private key, paste in a new file and store its path on the environment variable `BULLETIN_BOARD_IDENTIFICATION_PRIVATE_KEY`.
+b. Copy the private key and store that value on the environment variable `BULLETIN_BOARD_IDENTIFICATION_PRIVATE_KEY`.
+
+Regardless of the used method, when copying the private key remember to include the lines prefixed by `-----` and ensure that the private key is not lost between deployments and servers reboots and that only can be accessed by the application.
+
+## Configuration of the Bulletin Board application
+
+The Bulletin Board administrator will store the received public key in their server and will send you back an API key. To complete the setup process you should store this API key and the Bulletin Board URL address on the environment variables `BULLETIN_BOARD_API_KEY` and `BULLETIN_BOARD_SERVER`, respectively.
+
+The following YAML snippet with all the defined environment variables should be used in the `default` block of your application `config/secrets.yml` file. Maybe this is already done, as it was included in the Decidim applications generator during the development of the Elections module.
+
+```yaml
+  bulletin_board:
+    identification_private_key: |
+<%= ENV["BULLETIN_BOARD_IDENTIFICATION_PRIVATE_KEY"]&.indent(6) %>
+    server: <%= ENV["BULLETIN_BOARD_SERVER"] %>
+    api_key: <%= ENV["BULLETIN_BOARD_API_KEY"] %>
+```
+
+After restarting the Decidim instance, administrator users will be able to create elections on the configured Bulletin Board.

data/docs/services/etherpad.md

@@ -1,6 +1,10 @@
 # Etherpad
 
-Decidim can be integrated with Etherpad so meetings can have their own pads.
+On some cases, users need to have near real time collaborative writing, for instance for having the minutes on a physical meeting.
+
+To ease online/offline participation, Decidim can be integrated with Etherpad so meetings can have their own pads.
+
+## Integration
 
 In order to use it you need to have your own Etherpad deployment, you can do it
 with the Docker compose using the provided `docker-compose-etherpad.yml`.
@@ -13,5 +17,36 @@ docker swarm init # just one time
 docker stack deploy --compose-file docker-compose-etherpad.yml decidim-etherpad
 ```
 
-After deploying it, you should set the Etherpad host and API Key at
+After deploying Etherpad, you should get back to Decidim's server and set the Etherpad host and API Key at
 `config/initializers/decidim.rb` and `config/secrets.yml`
+
+An example snippet in `config/initializers/decidim.rb` may be:
+
+```ruby
+config.etherpad = {
+  server: Rails.application.secrets.etherpad[:server],
+  api_key: Rails.application.secrets.etherpad[:api_key],
+  api_version: Rails.application.secrets.etherpad[:api_version]
+}
+```
+
+and then in `config/secrets.yml`:
+
+```yaml
+  etherpad:
+    server: <%= ENV["ETHERPAD_SERVER"] %>
+    api_key: <%= ENV["ETHERPAD_API_KEY"] %>
+    api_version: <%= ENV["ETHERPAD_API_VERSION"] %>
+```
+
+## How is Etherpad Lite integrated in Meetings?
+
+To better understand this feature, the final idea is to have the three moments of a meeting covered on Decidim itself by default:
+
+- **Before the meeting**, you let know that the meeting is going to happen, where, when and what is going to be discussed
+- **During the meeting**, notes can be taken on a collaborative way
+- **After the meeting**, you upload the notes, minutes, metadata and/or pictures to have a record on what was discussed
+
+Pad creation can be enabled by administrators in each `Meetings` component. When enabled, the public view of a Meeting renders an iframe which encapsulates the integrated Pad. This Pad is automatically created before rendering, so there's nothing the user or the administrators has to do to see the Pad.
+
+The pad iframe is only accessible for 24 hours before and 72 hours after the meeting. After the meeting only the read only URL for this pad is shown.

data/docs/services/maps.md

@@ -0,0 +1,362 @@
+# Maps and geocoding
+
+Decidim has the ability to geocode proposals and meetings and display them on a
+map. Decidim has built-in support for the following map service providers:
+
+- [HERE Maps][link-here] (Recommended)
+  - Supports map tiles, static map images, geocoding and geocoding
+    autocompletion
+  - Easy to get started with, comes with a rather generous free plan
+  - [Configuring HERE Maps][anchor-configure-here-maps]
+- [Open Street Maps based services][link-osm-commercial]
+  - Please pick a service provider that provides all needed services (map tiles,
+    static map images, geocoding and geocoding autocompletion)
+  - We can't use the OSM's own services by their
+    [tile usage policy][link-osm-tile-usage].
+  - In case your service provider does not offer static map images, Decidim will
+    use the dynamic map tiles to generate a similar map element.
+  - As an alternative, you may also want to use your own self-hosted map servers
+    (see [Hosting your own map services][anchor-hosting-osm] for
+    more information)
+  - [Configuring Open Street Maps based service providers][anchor-configure-osm]
+
+If you want to integrate Decidim to some other map service provider, read how to
+[write your own integration code][link-docs-custom-maps] for that.
+
+## Configuring maps and geocoding
+
+After generating your app, you'll see that your `config/initializers/decidim.rb`
+file includes commented code about map services:
+
+```ruby
+# Map and Geocoder configuration
+# config.maps = {
+#   ...
+# }
+```
+
+The initializer comments provide examples for the services mentioned in this
+documentation. Please refer to the section below for the service you have
+registered for the maps functionality.
+
+If you want to enable geocoding in your app:
+
+1. Select a service provider for the maps functionality and register an account
+   with that provider
+1. Uncomment or add the code under the selected service provider in your
+   `config/initializers/decidim.rb`.
+1. Make sure your `config/secrets.yml` file has the needed section (it should
+   be added by the generator automatically).
+1. Configure the service provider credentials in `config/secrets.yml` and refer
+   to them from your `config/initializers/decidim.rb`.
+1. If you had your Rails server running, restart it so the changes apply.
+
+### Configuring HERE Maps
+
+Use the following configuration for HERE Maps:
+
+`config/initializers/decidim.rb`:
+
+```ruby
+# Map and Geocoder configuration
+# == HERE Maps ==
+config.maps = {
+  provider: :here,
+  api_key: Rails.application.secrets.maps[:api_key],
+  static: { url: "https://image.maps.ls.hereapi.com/mia/1.6/mapview" }
+}
+```
+
+`config/secrets.yml`:
+
+```yaml
+default: &default
+  # ...
+  maps:
+    api_key: <%= ENV["MAPS_API_KEY"] %>
+```
+
+`.env`:
+
+```bash
+MAPS_API_KEY=your_api_key_here
+```
+
+### Configuring Open Street Maps based service providers
+
+Use the following configuration for Open Street Maps based service providers:
+
+`config/initializers/decidim.rb`:
+
+```ruby
+# Map and Geocoder configuration
+# == OpenStreetMap (OSM) services ==
+config.maps = {
+  provider: :osm,
+  api_key: Rails.application.secrets.maps[:api_key],
+  dynamic: {
+    tile_layer: {
+      url: "https://tiles.example.org/{z}/{x}/{y}.png?key={apiKey}",
+      api_key: true,
+      attribution: %(
+        <a href="https://www.openstreetmap.org/copyright" target="_blank">&copy; OpenStreetMap</a> contributors
+      ).strip
+      # Translatable attribution:
+      # attribution: -> { I18n.t("tile_layer_attribution") }
+    }
+  },
+  # static: { url: "https://staticmap.example.org/" }, # optional
+  geocoding: { host: "nominatim.example.org", use_https: true },
+  autocomplete: { url: "https://photon.example.org/api/" }
+}
+```
+
+`config/secrets.yml`:
+
+```yaml
+default: &default
+  # ...
+  maps:
+    api_key: <%= ENV["MAPS_API_KEY"] %>
+```
+
+`.env`:
+
+```bash
+MAPS_API_KEY=your_api_key_here
+```
+
+For further information, see the service provider's documentation or take a look
+at the [Hosting your own map services][anchor-hosting-osm] section.
+
+### Combining multiple service providers
+
+It is also possible to combine multiple service providers for the different
+categories of map services. For instance, if you want to use HERE Maps for
+the map tiles but host the other services yourself, use the following
+configuration:
+
+```ruby
+# Map and Geocoder configuration
+# == Combination (OpenStreetMap default + HERE Maps dynamic map tiles) ==
+config.maps = {
+  provider: :osm,
+  dynamic: {
+    provider: :here,
+    api_key: Rails.application.secrets.maps[:here_api_key]
+  },
+  static: { url: "https://staticmap.example.org/" },
+  geocoding: { host: "nominatim.example.org", use_https: true },
+  autocomplete: { url: "https://photon.example.org/api/" }
+}
+```
+
+`config/secrets.yml`:
+
+```yaml
+default: &default
+  # ...
+  maps:
+    here_api_key: <%= ENV["MAPS_HERE_API_KEY"] %>
+```
+
+`.env`:
+
+```bash
+MAPS_HERE_API_KEY=your_api_key_here
+```
+
+### Disabling some of the map services
+
+When using the maps functionality, you should always aim to provide all the
+services for the user that are available in Decidim. However, not all service
+providers provide all these services, so at times you may need to disable some
+of them.
+
+The configuration syntax allows you to disable the map services one by one. For
+example, if you want to use HERE Maps as your default but disable the static map
+images and geocoding autocompletion functionality, you can use the following
+configuration:
+
+```ruby
+config.maps = {
+  provider: :here,
+  api_key: Rails.application.secrets.maps[:api_key],
+  static: false,
+  autocomplete: false
+}
+```
+
+Decidim works fine when some of the services are disabled individually but
+obviously, the disabled services are not available for Decidim users.
+
+### Global geocoder configurations
+
+In the Dedicim initialiser (`config/initializers/decidim.rb`) you will also see
+a commented section for the global geocoder configurations commented as follows:
+
+```ruby
+# Geocoder configurations ...
+# config.geocoder = {
+#   # geocoding service request timeout, in seconds (default 3):
+#   timeout: 5,
+#   # set default units to kilometers:
+#   units: :km,
+#   # caching (see https://github.com/alexreisner/geocoder#caching for details):
+#   cache: Redis.new,
+#   cache_prefix: "..."
+# }
+```
+
+This will change the global geocoding settings for your application. To learn
+more about these settings, take a look at the
+[Geocoder gem's documentation][link-geocoder].
+
+### Geocoding autocompletion configurations
+
+Each autocompletion geocoder has their own configurations and this may not apply
+for all geocoding services. The geocoder autocompletion integrations shipped
+with Decidim support the configurations shown in this section.
+
+If you want to customize the address format in the geocoding autocompletion
+fields, you can apply the following configuration to your geocoder settings:
+
+```ruby
+config.maps = {
+  # ... other configs ...
+  autocomplete: {
+    # For HERE:
+    address_format: [%w(street houseNumber), "city", "country"]
+    # For OSM/Photon:
+    # address_format: ["name", %w(street housenumber), "city", "country"]
+  }
+}
+```
+
+### Integrating with a new service provider
+
+If you want to integrate the map functionality with a new service provider, take
+a look at the [Custom map providers][link-docs-custom-maps] documentation.
+
+## Enabling maps and geocoding
+
+Once the maps functionality is configured, you'll need to activate it. As of
+April 2017, only proposals and meetings have maps and geocoding.
+
+### Proposals
+
+In order to enable geocoding for proposals you'll need to edit the component
+configuration and turn on "Geocoding enabled" configuration. This works for that
+specific component, so you can have geocoding enabled for proposals in a
+participatory process, and disabled for another proposals component in the same
+participatory process.
+
+### Meetings
+
+Meetings do not have a configuration option for geocoding. Instead, if geocoding
+is configured it will try to geocode the address every time you create or update
+a meeting. As of April 2017 there is no way to enable or disable geocoding per
+meetings component.
+
+## Hosting your own map services
+
+It is recommended to use a commercial service provider for all the map
+functionality to get up and running more easily. Hosting all these services
+yourself and keeping everything up to date is time consuming and rather complex.
+If the related complexity or the required time is not an issue, feel free to
+setup the following services on your own servers.
+
+### Map tiles: Open Street Maps tile server
+
+You will need a [map tiles][link-wiki-map-tiles] server which is used for the
+dynamic maps that the user can move themselves.
+
+Follow these instructions to setup your tiles server:
+
+https://opentileserver.org/
+
+In the example configuration, we assume you have used the following domain for
+the tiles server:
+
+https://tiles.example.org
+
+### Static map images: Openstreetmap static maps server (osm-static-maps)
+
+Some pages in Decidim display static map images which need to be fetched from
+an external server. The tiles server does not provide such static images by
+itself because one static map image may need multiple tiles to be combined into
+one. The static map image is therefore dynamically generated based on the
+parameters passed for the static map request (such as image dimensions and the
+geocoordinates of the map image position).
+
+The Open Street Maps community has made multiple open source
+[static maps image services][link-wiki-static-maps] from which you can pick
+freely but Decidim currently supports only
+[osm-static-maps][link-osm-static-maps] with the Open Street Maps services.
+
+Follow these instructions to setup your static map images server:
+
+https://github.com/jperelli/osm-static-maps#3-standalone-sample-server
+
+In the example configuration, we assume you have used the following domain for
+the static maps image server:
+
+https://staticmap.example.org
+
+Setting up this service is optional. If you do not configure a static map URL
+for the OSM based map services, Decidim will use the dynamic map tiles to
+generate a similar map element.
+
+### Geocoding: Nominatim geocoding server
+
+[Nominatim][link-osm-nominatim] makes it possible to place points on the Decidim
+maps based on addresses. This service provides geocoding capabilities by turning
+human readable addresses to [geographic coordinates][link-wiki-geocoordinates].
+
+Follow these instructions to setup your geocoding server:
+
+http://nominatim.org/release-docs/latest/admin/Installation/
+
+In the example configuration, we assume you have used the following domain for
+the geocoding server:
+
+https://nominatim.example.org
+
+### Geocoding autocompletion: Photon geocoding server
+
+[Photon][link-osm-photon] makes it possible to provide the autocompletion
+service for people writing addresses to the address fields available in Decidim.
+It uses the Open Street Maps data to serve the autocompletion requests. When
+people select one of the suggested addresses, it will also tell Decidim the map
+point for that address.
+
+Follow these instructions to setup your geocoding autocompletion server:
+
+https://github.com/komoot/photon#installation
+
+In the example configuration, we assume you have used the following domain for
+the Photon geocoding server for the autocompletion functionality:
+
+https://photon.example.org
+
+### Configure Decidim
+
+After you have all these services running, change your Decidim configurations
+to use these services. Read the
+[Configuring Open Street Maps based service providers][anchor-configure-osm]
+section for more information.
+
+[anchor-hosting-osm]: #hosting-your-own-map-services
+[anchor-configure-here-maps]: #configuring-here-maps
+[anchor-configure-osm]: #configuring-open-street-maps-based-service-providers
+[link-docs-custom-maps]: /docs/customization/maps.md
+[link-here]: http://here.com
+[link-geocoder]: https://github.com/alexreisner/geocoder
+[link-osm-commercial]: https://wiki.openstreetmap.org/wiki/Commercial_OSM_Software_and_Services
+[link-osm-nominatim]: https://wiki.openstreetmap.org/wiki/Nominatim
+[link-osm-static-maps]: https://github.com/jperelli/osm-static-maps
+[link-osm-photon]: https://github.com/komoot/photon
+[link-osm-tile-usage]: https://operations.osmfoundation.org/policies/tiles/
+[link-wiki-geocoordinates]: https://en.wikipedia.org/wiki/Geographic_coordinate_system
+[link-wiki-map-tiles]: https://wiki.openstreetmap.org/wiki/Tiles
+[link-wiki-static-maps]: https://wiki.openstreetmap.org/wiki/Static_map_images