ferru11 / decidim

The participatory democracy framework

Decidim

Code quality

Project management [See on Waffle.io]

---

Decidim is a participatory democracy framework written on Ruby on Rails originally developed for the Barcelona City government online and offline participation website. Installing this libraries you'll get a generator and gems to help you develop web applications like the ones found on example applications.

What do you need to do?

• Contribute to the project
• Create & browse development app
• Install "Decidim" for an organization
• Upgrade an already existing "Decidim" installation
• Use Docker to deploy "Decidim"
• Check current components
• Further configuration
• Technical tradeoffs

---

Installation instructions

First of all, you need to install the decidim gem, which currently is in a prerelease status.

$ gem install decidim decidim-core --pre

Afterwards, you can create an application with the nice decidim executable:

$ decidim decidim_application
$ cd decidim_application

Note: These steps will be replaced by a simple gem install decidim && decidim decidim_application once the gem is released.

You should now setup your database:

$ rails db:setup

This will also create some default data so you can start testing the app:

• A Decidim::System::Admin with email [email protected] and password decidim123456, to log in at /system.
• A Decidim::Organization named Decidim Staging. You probably want to change its name and hostname to match your needs.
• A Decidim::User acting as an admin for the organization, with email [email protected] and password decidim123456.
• A Decidim::User that also belongs to the organization but it's a regular user, with email [email protected] and password decidim123456.

This data won't be created in production environments, if you still want to do it, run:

$ SEED=true rails db:setup

You can now start your server!

$ rails s

Upgrade instructions

$ bundle update decidim

And don't forget to run the upgrade script:

$ rails decidim:upgrade

If new migrations appear, remember to:

$ rails db:migrate

Docker instructions

You can use Docker instead of installing the gems yourself. Run docker-compose build and then you can generate a new decidim application using docker-compose run --rm decidim bundle exec bin/decidim <app-name>.

Also you can run it as a standalone container like this: docker run --rm -v $(pwd):/tmp -it codegram/decidim bundle exec bin/decidim /tmp/<app-name>

Now you have a new Decidim app created at <app-name> 🎉

How to contribute

In order to develop on decidim, you'll need:

• PostgreSQL 9.4+
• Ruby 2.4.1
• NodeJS with yarn (JavaScript dependency manager, can be installed with npm install yarn)
• ImageMagick
• PhantomJS

The easiest way to work on decidim is to clone decidim's repository and install its dependencies

$ git clone [email protected]:AjuntamentdeBarcelona/decidim.git
$ cd decidim
$ bundle install
$ yarn install

You have several rake tasks available for you:

• bundle exec rake development_app: Creates a development app inside decidim_development which you can use to run an application with the gems in your path.
• bundle exec rake test_all: Generates a test app for every engine and runs their tests.
• bundle exec rake generate_all: Generates all the tests apps but doesn't run the tests - this is useful is you want to run them manually afterwards.
• cd <component> and do bundle exec rspec spec to run those particular tests.

Browse Decidim

After you create a development app (bundle exec rake development_app):

• cd development_app
• bundle exec rails s
• Go to 'http://localhost:3000'

Optionally, you can log in as: [email protected] | decidim123456

Also, if you want to verify yourself against the default authorization handler use a document number ended with "X".

Browse Admin Interface

After you create a development app (bundle exec rake development_app):

• cd development_app
• bundle exec rails s
• Go to 'http://localhost:3000/admin'
• Login data: [email protected] | decidim123456

Components

Component	Description
Admin	This library adds an administration dashboard so users can manage their organization, participatory processes and all other entities.
API	This library exposes a GraphQL API to programatically interact with the Decidim platform via HTTP
Comments	The Comments module adds the ability to include comments to any resource which can be commentable by users.
Core	The basics of Decidim: users, participatory processes, etc. This is the only required engine to run Decidim, all the others are optional.
Dev	This gem aids the local development of Decidim's features.
Meeting	The Meeeting module adds meeting to any participatory process. It adds a CRUD engine to the admin and public view scoped inside the participatory process.
Pages	The Pages module adds static page capabilities to any participatory process. It basically provides an interface to include arbitrary HTML content to any step.
Proposals	The Proposals module adds one of the main features of Decidim: allows users to contribute to a participatory process by creating proposals.
System	Multitenant Admin to manage multiple organizations in a single installation

Further configuration

• Social providers integration: Enable sign up from social networks.
• Analytics: How to enable analytics

Technical tradeoffs

Architecture

This is not your tipical Ruby on Rails Vanilla App. We've tried that using Consul but we've found some problems on reutilization, adaptation, modularization and configuration. You can read more about that on "Propuesta de Cambios de Arquitectura de Consul".

Turbolinks

Decidim doesn't support turbolinks so it isn't included on our generated apps and it's removed for existing Rails applications which install the Decidim engine.

The main reason for this is we are injecting some scripts into the body for some individual pages and Turbolinks loads the scripts in parallel. For some libraries like leaflet it's very inconvenient because its plugins extend an existing global object.

The support of Turbolinks was dropped in d8c7d9f. If you're interested in bringing turbolinks back, further discussion is welcome.

Following our license

If you plan to release your application you'll need to publish it using the same license: GPL Affero 3. We recommend doing that on Github before publishing, you can read more on "Being Open Source From Day One is Especially Important for Government Projects". If you have any trouble doing that you can contact us on Gitter.

Example applications

• Demo
• Decidim Barcelona
• L'H ON dels barris