Document how to work locally with Elections/Votings (#10870)

* Document how to work locally with Elections/Votings

* Fix spelling

* Add testing instructions and docker-compose configuration

* Use "there is" instead of "there's"

* Document exception shown if the service is not running

* Remove unecessary details from documented exception

* Fix markdownlint offenses

decidim-elections/README.md

@@ -10,6 +10,40 @@ Elections will be available as a Component for a Participatory Space.
 
 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/). To create this connection, please check the [instructions](https://docs.decidim.org/en/services/elections_bulletin_board/).
 
+## Development
+
+In the case that you only want to use this module for local development or testing purposes, you have an example docker-compose configuration in `docs/`. Mind that this setup is not recommended for production environments. It works with default seeds and configurations for a Decidim installation, so you should not do anything.
+
+```bash
+cd docs/docker/bulletin_board
+docker-compose up
+```
+
+One important caveat is that as the Trustees' key generation functionality uses the IndexedDB API, and at least in Firefox there is unsupported in the Private Browsing mode (see ticket [#1639542 in Mozilla's Bugzilla](https://bugzilla.mozilla.org/show_bug.cgi?id=1639542)). As a workaround there is the [Firefox Multi-Account Containers addon](https://addons.mozilla.org/es/firefox/addon/multi-account-containers/).
+
+## Testing
+
+Besides the [set-up typical for Decidim](https://docs.decidim.org/en/develop/develop/testing), for some of the specs a Bulletin Board installation is needed, running in port 5017 by default with the `DATABASE_CLEANER_ALLOW_REMOTE_DATABASE_URL` environment variable set up with the "true" string. There is a working configuration on `docs`.
+
+```bash
+cd docs/docker/bulletin_board_test
+docker-compose up
+```
+
+As the Bulletin Board service is a necessary dependency for this module to work, if it is not running while executing the specs, the following exception will be shown.
+
+> Failure/Error: Decidim::Elections.bulletin_board.reset_test_database
+>
+> StandardError:
+> Sorry, something went wrong
+>
+> ./spec/shared/test_bulletin_board_shared_context.rb:6:in 'block (2 levels) in <top (required)>'
+> (...)
+> -- Caused by:
+> Errno::ECONNREFUSED:
+> Connection refused - connect(2) for 127.0.0.1:5017
+> ./spec/shared/test_bulletin_board_shared_context.rb:6:in 'block (2 levels) in <top (required)>'
+
 ## Installation
 
 Add this line to your application's Gemfile:

decidim-elections/docs/docker/bulletin_board/docker-compose.yml

@@ -0,0 +1,22 @@
+version: '3.4'
+services:
+  db:
+    image: postgres:11
+    environment:
+      - POSTGRES_PASSWORD=postgres
+    volumes:
+      - pg-data:/var/lib/postgresql/data
+  app:
+    image: decidim/decidim-bulletin-board:0.24.1
+    environment:
+      - DATABASE_URL=postgresql://postgres:postgres@db/decidim_bulletin_board_test
+      - RAILS_ENV=test
+      - RAILS_LOG_TO_STDOUT=true
+      - RAILS_SERVE_STATIC_FILES=enabled
+      - SEED=1
+      - IDENTIFICATION_PRIVATE_KEY='{"kty":"RSA","n":"zMXsZpYPKkDlSmezX898y7zNOaJ7ENIN4kj4UhQ95Vm4HlgTpIs2VMMsO0eqynMaOR_G1mXdqbpbaJtXijBe4V8323QwGm6WVAa71E7pDXa5g6-uo5f8GePitN0YER9y2yNQN4uTaNzJiWV2uLBUYfMdj3SIif31YwLULHAOj3B_oleFK8coE_Qr3NzATcYBmsqE8AR4NljxTO6KDmP1SLdf5GBOBhOAIFbnL_Kpj2xkm7MS3hjMVKpiRhqA1UgX5oKZ8ixBv46fNJF0pBsHi3fHNjK9oZzgdx_AI-YFpdE_40-8bh_g9sWzxacqOM2-MdQLHbvRPEVltO3E8tr6I5YWrylcP7l9VD8OJeqjq2qFYHnGYdmLoD2XuXmI9EuBvSb9H4-qcartxZSIQCimKib_fxZvgrG1FSRRhK6YpvIdGv4-G2zfCCRsC4XD80TYI2bf-oYCoy7eU3_eVHFMV2yg4p1Wnuw2Vgq0edPL_bKaV9JvGx7F-U5juxNN0WZR9LzbPl4ReejzN95lyHgbj0nTH_u3bSpZmgJrQF-PwdnPcG46deVjJgUeosrlC4lQxVrRz0GL58BuFunnz2uYDBDrcJCiG60EbdkAFHjOcXU4wrUWATin7je_aqdBXhSnkTafcJAMvL7Y2Ld7vDge8nLqjAVlAi5am3rN0kqKT6M","e":"AQAB","kid":"a8e86f02ca27e1861bfc49e2a9a4614ca9068f8efdb6d42d19d3aab0eb2a31be"}'
+    ports:
+      - 8000:8000
+
+volumes:
+  pg-data:

decidim-elections/docs/docker/bulletin_board_test/docker-compose.yml

@@ -0,0 +1,23 @@
+version: '3.4'
+services:
+  db:
+    image: postgres:11
+    environment:
+      - POSTGRES_PASSWORD=postgres
+    volumes:
+      - pg-data:/var/lib/postgresql/data
+  app:
+    image: decidim/decidim-bulletin-board:0.24.1
+    environment:
+      - DATABASE_URL=postgresql://postgres:postgres@db/decidim_bulletin_board_test
+      - RAILS_ENV=test
+      - RAILS_LOG_TO_STDOUT=true
+      - RAILS_SERVE_STATIC_FILES=enabled
+      - SEED=1
+      - IDENTIFICATION_PRIVATE_KEY='{"kty":"RSA","n":"zMXsZpYPKkDlSmezX898y7zNOaJ7ENIN4kj4UhQ95Vm4HlgTpIs2VMMsO0eqynMaOR_G1mXdqbpbaJtXijBe4V8323QwGm6WVAa71E7pDXa5g6-uo5f8GePitN0YER9y2yNQN4uTaNzJiWV2uLBUYfMdj3SIif31YwLULHAOj3B_oleFK8coE_Qr3NzATcYBmsqE8AR4NljxTO6KDmP1SLdf5GBOBhOAIFbnL_Kpj2xkm7MS3hjMVKpiRhqA1UgX5oKZ8ixBv46fNJF0pBsHi3fHNjK9oZzgdx_AI-YFpdE_40-8bh_g9sWzxacqOM2-MdQLHbvRPEVltO3E8tr6I5YWrylcP7l9VD8OJeqjq2qFYHnGYdmLoD2XuXmI9EuBvSb9H4-qcartxZSIQCimKib_fxZvgrG1FSRRhK6YpvIdGv4-G2zfCCRsC4XD80TYI2bf-oYCoy7eU3_eVHFMV2yg4p1Wnuw2Vgq0edPL_bKaV9JvGx7F-U5juxNN0WZR9LzbPl4ReejzN95lyHgbj0nTH_u3bSpZmgJrQF-PwdnPcG46deVjJgUeosrlC4lQxVrRz0GL58BuFunnz2uYDBDrcJCiG60EbdkAFHjOcXU4wrUWATin7je_aqdBXhSnkTafcJAMvL7Y2Ld7vDge8nLqjAVlAi5am3rN0kqKT6M","e":"AQAB","kid":"a8e86f02ca27e1861bfc49e2a9a4614ca9068f8efdb6d42d19d3aab0eb2a31be"}'
+      - DATABASE_CLEANER_ALLOW_REMOTE_DATABASE_URL=true
+    ports:
+      - 5017:8000
+
+volumes:
+  pg-data: