decidim 0.23.6 → 0.24.0.rc1

data/docs/{manual-installation.md → modules/install/pages/manual.adoc}

@@ -1,25 +1,26 @@
-# Manual installation tutorial
+= Manual installation tutorial
 
-## Step by step
+== Step by step
 
 In order to develop on decidim, you'll need:
 
-* **Git** 2.15+
-* **PostgreSQL** 9.5+
-* **Ruby** 2.5.0 (2.3+ should work just fine, but that's the version we test against)
-* **NodeJS** 9.x.x
-* **ImageMagick**
-* **Chrome** browser and [chromedriver](https://sites.google.com/a/chromium.org/chromedriver/).
+* *Git* 2.15+
+* *PostgreSQL* 9.5+
+* *Ruby* 2.5.0 (2.3+ should work just fine, but that's the version we test against)
+* *NodeJS* 9.x.x
+* *ImageMagick*
+* *Chrome* browser and https://sites.google.com/a/chromium.org/chromedriver/[chromedriver].
 
-We're starting with an Ubuntu 16.04 LTS. This is an opinionated guide and YMMV, so if you're free to use the technology that you fell most comfortable on. If you have any doubts and you're blocked you can go and ask on [our Gitter](https://gitter.im/decidim/decidim). We recommend that you follow some Ruby on Rails tutorials (like [Getting Started with Ruby on Rails](http://guides.rubyonrails.org/getting_started.html)) and have some knowledge on how gems and engines work.
+We're starting with an Ubuntu 16.04 LTS. This is an opinionated guide and YMMV, so if you're free to use the technology that you fell most comfortable on. If you have any doubts and you're blocked you can go and ask on https://gitter.im/decidim/decidim[our Gitter]. We recommend that you follow some Ruby on Rails tutorials (like http://guides.rubyonrails.org/getting_started.html[Getting Started with Ruby on Rails]) and have some knowledge on how gems and engines work.
 
 On this tutorial we'll see how to install rbenv, PostgreSQL and Decidim, and how to configure everything together.
 
-### Installing rbenv
+=== Installing rbenv
 
-First we're going to install rbenv, for managing various ruby versions. We're following the guide from [DigitalOcean](https://www.digitalocean.com/community/tutorials/how-to-install-ruby-on-rails-with-rbenv-on-ubuntu-16-04). You could also use [rvm](https://rvm.io/) as an alternative on this step. On these instruction we're using the latest ruby published version at the moment (2.5.3), but you should check this out on [Ruby official website](https://www.ruby-lang.org/en/downloads/).
+First we're going to install rbenv, for managing various ruby versions. We're following the guide from https://www.digitalocean.com/community/tutorials/how-to-install-ruby-on-rails-with-rbenv-on-ubuntu-16-04[DigitalOcean]. You could also use https://rvm.io/[rvm] as an alternative on this step. On these instruction we're using the latest ruby published version at the moment (2.5.3), but you should check this out on https://www.ruby-lang.org/en/downloads/[Ruby official website].
 
-```bash
+[source,bash]
+----
 sudo apt update
 sudo apt install -y build-essential autoconf bison libssl-dev libyaml-dev libreadline-dev zlib1g-dev libncurses5-dev libffi-dev libgdbm3 libgdbm-dev libicu-dev
 git clone https://github.com/rbenv/rbenv.git ~/.rbenv
@@ -31,83 +32,92 @@ rbenv install 2.5.3
 rbenv global 2.5.3
 echo "gem: --no-document" > ~/.gemrc
 gem install bundler
-```
+----
 
-### Installing PostgreSQL
+=== Installing PostgreSQL
 
 Now we're going to install PostgreSQL for the database:
 
-```bash
+[source,bash]
+----
 sudo apt install -y postgresql libpq-dev
 sudo -u postgres psql -c "CREATE USER decidim_app WITH SUPERUSER CREATEDB NOCREATEROLE PASSWORD 'thepassword'"
-```
+----
 
 You need to change the password (on this example is "thepassword") and save it somewhere to configure it later with the application.
 
-### Installing Decidim
+=== Installing Decidim
 
 Next, we need to install the `decidim` gem:
 
-```bash
+[source,bash]
+----
 gem install bootsnap
 gem install listen
 gem install decidim
-```
+----
 
 Afterwards, we can create an application with the nice `decidim` executable, where `decidim_application` is your application name (ie decidim.barcelona):
 
-```bash
+[source,bash]
+----
 decidim decidim_application
 cd decidim_application
-```
+----
 
 We recommend that you save it all on Git.
 
-```bash
+[source,bash]
+----
 git init .
 git commit -m "Initial commit. Generated with Decidim 0.X https://decidim.org"
-```
+----
 
-### Configure the database
+=== Configure the database
 
-You need to modify your secrets (see `config/database.yml`). For this you can use [figaro](https://github.com/laserlemon/figaro), [dotenv](https://github.com/bkeepers/dotenv) or [rbenv-vars](https://github.com/rbenv/rbenv-vars). You should always be careful of not uploading your plain secrets on git or your version control system. You can also upload the encrypted secrets, using the sekrets gem or if you're on Ruby on Rails greater than 5.1 you can do it natively.
+You need to modify your secrets (see `config/database.yml`). For this you can use https://github.com/laserlemon/figaro[figaro], https://github.com/bkeepers/dotenv[dotenv] or https://github.com/rbenv/rbenv-vars[rbenv-vars]. You should always be careful of not uploading your plain secrets on git or your version control system. You can also upload the encrypted secrets, using the sekrets gem or if you're on Ruby on Rails greater than 5.1 you can do it natively.
 
 For instance, for working with figaro, add this to your `Gemfile`:
 
-```ruby
+[source,ruby]
+----
 gem "figaro"
-```
+----
 
 Then install it:
 
-```bash
+[source,bash]
+----
 bundle install
 bundle exec figaro install
-```
+----
 
 Next add this to your `config/application.yml`, using the setup the PostgreSQL database name, user and password that you configure before.
 
-```yaml
+[source,yaml]
+----
 DATABASE_HOST: localhost
 DATABASE_USERNAME: decidim_app
 DATABASE_PASSWORD: your_password
-```
+----
 
 Finally, save it all to git:
 
-```bash
+[source,bash]
+----
 git add .
 git commit -m "Adds figaro configuration management"
-```
+----
 
-### Initializing your app for local development
+=== Initializing your app for local development
 
 We should now setup your database:
 
-```bash
+[source,bash]
+----
 bin/rails db:create db:migrate
 bin/rails db:seed
-```
+----
 
 This will also create some default data so you can start testing the app:
 
@@ -118,18 +128,20 @@ This will also create some default data so you can start testing the app:
 
 This data won't be created in production environments, if you still want to do it, run:
 
-```bash
+[source,bash]
+----
 SEED=true rails db:setup
-```
+----
 
-#### Notes
+==== 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
+[source,bash]
+----
 bin/rails s
-```
+----
 
-Visit [http://localhost:3000](http://localhost:3000) to see your app running. 🎉 🎉
+Visit http://localhost:3000 to see your app running. 🎉 🎉

data/docs/modules/install/pages/update.adoc

@@ -0,0 +1,95 @@
+= Updating Decidim
+
+IMPORTANT: This section was initially copied from https://platoniq.github.io/decidim-install/decidim-update/[Platoniq's Guide]
+
+Because Decidim is a gem in our system, to update it we will have to edit our `Gemfile` and specify the new version number.
+
+To keep our system up to date, we can visit the page https://github.com/decidim/decidim/releases and compare with our `Gemfile`. See if the lines specifying the gem called "decidim-something" are followed by the number corresponding to the latest release:
+
+[source,ruby]
+----
+gem "decidim", "0.20.1"
+gem "decidim-conferences", "0.20.1"
+gem "decidim-consultations", "0.20.1"
+gem "decidim-initiatives", "0.20.1"
+
+gem "decidim-dev", "0.20.1"
+----
+
+For example, if the latest release is 0.16 we could decide to update.
+
+To update, usually requires only to change the old version number on these gems to the new one. For instance, previous example should be:
+
+[source,ruby]
+----
+gem "decidim", "0.21"
+gem "decidim-conferences", "0.21"
+gem "decidim-consultations", "0.21"
+gem "decidim-initiatives", "0.21"
+
+gem "decidim-dev", "0.21"
+----
+
+After doing that, you need to execute these commands:
+
+[source,console]
+----
+bundle update decidim
+bin/rails decidim:upgrade
+bin/rails db:migrate
+----
+
+In theory, that would be all. However, you need to be careful in certain situations, specially if your copy of Decidim has many code modifications. We'd recommend to always test the upgrade following Ruby on Rails best practices: working with development mode in localhost, deploying to a staging/preproduction server to test it manually (specially your modifications) and finally deploying to production. As an alternative you can test the upgrade in a separate machine with the same configuration (If using Digitalocean you can create an snapshot of the server, tested the update, and then remove it, similar process on other providers).
+
+== From git repositories
+
+For managing the gems we use the standard Rails gem called Bundler, where you can also point to https://bundler.io/v2.1/guides/git.html[git repositories and branches]. This is specially useful if you want to try an unreleased version, then you can do so by pointing to the release branch.
+
+[source,ruby]
+----
+gem "decidim", git: "https://github.com/decidim/decidim", branch: "release/0.22-stable"
+gem "decidim-conferences", git: "https://github.com/decidim/decidim", branch: "release/0.22-stable"
+gem "decidim-consultations", git: "https://github.com/decidim/decidim", branch: "release/0.22-stable"
+gem "decidim-initiatives", git: "https://github.com/decidim/decidim", branch: "release/0.22-stable"
+
+gem "decidim-dev", git: "https://github.com/decidim/decidim", branch: "release/0.22-stable"
+----
+
+== DRY
+
+You can also work with variables in your Gemfile so you can keep it DRY (Don't Repeat Yourself):
+
+[source,ruby]
+----
+DECIDIM_VERSION = "0.21"
+
+gem "decidim", DECIDIM_VERSION
+gem "decidim-conferences", DECIDIM_VERSION
+gem "decidim-consultations", DECIDIM_VERSION
+gem "decidim-initiatives", DECIDIM_VERSION
+
+gem "decidim-dev", DECIDIM_VERSION
+----
+
+or
+
+[source,console]
+----
+DECIDIM_VERSION = { git: 'https://github.com/decidim/decidim.git', branch: 'release/0.22-stable' }
+
+gem "decidim", DECIDIM_VERSION
+gem "decidim-conferences", DECIDIM_VERSION
+gem "decidim-consultations", DECIDIM_VERSION
+gem "decidim-initiatives", DECIDIM_VERSION
+
+gem "decidim-dev", DECIDIM_VERSION
+----
+
+
+[discrete]
+== Recommendations
+
+. Make a full backup of the database before updating, just in case something unexpected happens.
+. If you are more than update away. Always update from one version to the immediately next one and then repeat the process until you are up to date.
+. Always check the instructions for a certain version upgrade in https://github.com/decidim/decidim/releases. Some releases require to perform certain actions as they may change some database structures. Follow that instructions if you are affected.
+. Check also the file https://github.com/decidim/decidim/blob/develop/CHANGELOG.md It may have relevant information for updates between versions.

data/docs/{services/activejob.md → modules/services/pages/activejob.adoc}

@@ -1,7 +1,7 @@
-# ActiveJob
+= ActiveJob
 
-For some kind of actions to work on production (for instance, sending emails on user registration) you need to configure an [ActiveJob](http://edgeguides.rubyonrails.org/active_job_basics.html) backend on your application.
+For some kind of actions to work on production (for instance, sending emails on user registration) you need to configure an http://edgeguides.rubyonrails.org/active_job_basics.html[ActiveJob] backend on your application.
 
-If you don't want to introduce any other external dependencies for `decidim` (such as `redis`), you can use the `delayed_job` backend. That setup only depends on an underlying database which is already a requirement for `decidim` to work. Add the [delayed_job](https://github.com/collectiveidea/delayed_job/) gem to your `Gemfile` and follow the instructions in its readme to set it up.
+If you don't want to introduce any other external dependencies for `decidim` (such as `redis`), you can use the `delayed_job` backend. That setup only depends on an underlying database which is already a requirement for `decidim` to work. Add the https://github.com/collectiveidea/delayed_job/[delayed_job] gem to your `Gemfile` and follow the instructions in its readme to set it up.
 
 However, Decidim is agnostic on which kind of backend do you use, so feel free to set up the backend (ie `sidekiq`, `resque`, etc) you like the most.

data/docs/modules/services/pages/elections_bulletin_board.adoc

@@ -0,0 +1,52 @@
+= Elections Bulletin Board
+
+[CAUTION]
+====
+This is a work in progress and is not fully working yet.
+====
+
+In order to celebrate https://en.wikipedia.org/wiki/End-to-end_auditable_voting_systems[End-to-end auditable votings] using the Elections module, you will need to connect your Decidim instance with an instance of the https://github.com/decidim/decidim-bulletin-board/[Decidim Bulletin Board application], 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:
+
+[source,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. Together with the key, send your *Authority name* to the Bulletin Board administrator and store its value on the environment variable `BULLETIN_BOARD_AUTHORITY_NAME`.
+
+After that, copy the private key and store that value on the environment variable `BULLETIN_BOARD_IDENTIFICATION_PRIVATE_KEY`.
+
+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.
+
+[source,yaml]
+----
+  bulletin_board:
+    identification_private_key: <%= ENV["BULLETIN_BOARD_IDENTIFICATION_PRIVATE_KEY"] %>
+    server: <%= ENV["BULLETIN_BOARD_SERVER"] %>
+    api_key: <%= ENV["BULLETIN_BOARD_API_KEY"] %>
+    number_of_trustees: <%= ENV["BULLETIN_BOARD_NUMBER_OF_TRUSTEES"] %>
+    authority_name: <%= ENV["BULLETIN_BOARD_AUTHORITY_NAME"] %>
+    scheme:
+      name: <%= ENV["BULLETIN_BOARD_SCHEME_NAME"] %>
+      parameters:
+        quorum: <%= ENV["BULLETIN_BOARD_SCHEME_QUORUM"] %>
+----
+
+After restarting the Decidim instance, administrator users will be able to create elections on the configured Bulletin Board.
+
+== Scheduled tasks
+
+A *crontab* line must be added to your server to be able to open and close the Ballot Box for the elections automatically. You could use https://github.com/javan/whenever[Whenever] to manage it directly from the APP. You probably want to schedule a `bundle exec rake decidim_elections:scheduled_tasks` every hour.

data/docs/{services/etherpad.md → modules/services/pages/etherpad.adoc}

@@ -1,51 +1,54 @@
-# Etherpad
+= Etherpad
 
 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
+== 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`.
 
 You should edit that file to configure the environment variables and then run:
 
-```sh
+[source,sh]
+----
 docker swarm init # just one time
 
 docker stack deploy --compose-file docker-compose-etherpad.yml decidim-etherpad
-```
+----
 
 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
+[source,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
+[source,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?
+== 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
+* *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.
 

data/docs/modules/services/pages/maps.adoc

@@ -0,0 +1,311 @@
+= 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:
+
+* http://here.com[HERE Maps] (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,Configuring HERE Maps>>
+* https://wiki.openstreetmap.org/wiki/Commercial_OSM_Software_and_Services[Open Street Maps based services]
+ ** 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 https://operations.osmfoundation.org/policies/tiles/[tile usage policy].
+ ** 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,Hosting your own map services>> for more information)
+ ** <<configuring-open-street-maps-based-service-providers,Configuring Open Street Maps based service providers>>
+
+If you want to integrate Decidim to some other map service provider, read how to xref:/docs/customization/maps.adoc[write your own integration code] 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:
+
+[source,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:
+
+. Select a service provider for the maps functionality and register an account with that provider
+. Uncomment or add the code under the selected service provider in your `config/initializers/decidim.rb`.
+. Make sure your `config/secrets.yml` file has the needed section (it should be added by the generator automatically).
+. Configure the service provider credentials in `config/secrets.yml` and refer to them from your `config/initializers/decidim.rb`.
+. 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`:
+
+[source,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`:
+
+[source,yaml]
+----
+default: &default
+  # ...
+  maps:
+    api_key: <%= ENV["MAPS_API_KEY"] %>
+----
+
+`.env`:
+
+[source,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`:
+
+[source,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`:
+
+[source,yaml]
+----
+default: &default
+  # ...
+  maps:
+    api_key: <%= ENV["MAPS_API_KEY"] %>
+----
+
+`.env`:
+
+[source,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,Hosting your own map services>> 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:
+
+[source,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`:
+
+[source,yaml]
+----
+default: &default
+  # ...
+  maps:
+    here_api_key: <%= ENV["MAPS_HERE_API_KEY"] %>
+----
+
+`.env`:
+
+[source,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:
+
+[source,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:
+
+[source,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 https://github.com/alexreisner/geocoder[Geocoder gem's documentation].
+
+=== 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:
+
+[source,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 xref:/docs/customization/maps.adoc[Custom map providers] 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 https://wiki.openstreetmap.org/wiki/Tiles[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 https://wiki.openstreetmap.org/wiki/Static_map_images[static maps image services] from which you can pick freely but Decidim currently supports only https://github.com/jperelli/osm-static-maps[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
+
+https://wiki.openstreetmap.org/wiki/Nominatim[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 https://en.wikipedia.org/wiki/Geographic_coordinate_system[geographic coordinates].
+
+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
+
+https://github.com/komoot/photon[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,Configuring Open Street Maps based service providers>> section for more information.