Getting started with Decidim

What is Decidim?

Decidim is a participatory democracy framework based on multiple Ruby on Rails engines that are mounted on top of a Ruby on Rails application. This system allows separating the Decidim core code from any custom code needed in Decidim installations. This approach also makes it easy to keep the core code updated while maintaining any custom functionality added to the platform separated from the core code.

These libraries (gems) are published to Rubygems.org, and they are added to the Decidim applications by defining them as external dependencies within the Ruby on Rails application.

We may refer to engines, libraries, gems, or modules; they are mostly the same. Technically there are some differences with these terms but when you first start learning about Decidim and Ruby on Rails, you can see them as synonyms.

If you want to start your own installation of Decidim, you do not need to clone the Decidim source code repository. Keep reading to find out how to install Decidim.

Creating your Decidim app

A. Recommended: manual installation

If you know Ruby and have already worked with Ruby on Rails, you need to know that decidim is a gem and a command line utility that generates a Decidim application. The generated application utilizes the other gems provided by the Decidim project to benefit from the functionality provided by each gem.

The flow is: install the decidim gem, generate a Ruby on Rails app, enjoy.

gem install decidim
decidim decidim_application

You can see the official manual installation tutorial, and also you have another manual installation tutorial made by the nice people of Platoniq.

B. Installation script [experimental]

There is also an installation script made by Platoniq that allows you to install Decidim automatically. You can even check it on a Vagrant virtual machine if you want to. More information.

wget -O install-decidim.sh https://raw.githubusercontent.com/Platoniq/decidim-install/master/script/install-decidim.sh
chmod +x install-decidim.sh
./install-decidim.sh decidim_application

Initializing your application for local development

The commands below will add lots of example seed data to the Decidim application. This may be confusing for new users if you only want to use Decidim for a specific purpose, such as collecting proposals or arranging participatory budgeting. If you want to start with an empty database (without any seeds) and configure the system yourself, please refer to Empty database installation manual.

You should now setup your database:

bin/rails db:create db:migrate db:seed

This will also create some example data through the seeds so that you can start testing the application straight away. The following table contains some example user accounts that you can start testing the system with.

Table 1. Default seed’s users
Type	Email	Password	URL	Description
Decidim::System::Admin	system@example.org	decidim123456789	/system	Administrator for the multitenant
Decidim::User	admin@example.org	decidim123456789	/admin	Administrator for the organization
Decidim::User	user@example.org	decidim123456789	/user/sign_in	User for the organization

This data will not be created in production environments. If you insist on adding it in production, run: $ SEED=true rails db:setup. We recomend that you first login as a system user and edit the hostname for the organization. Set it as your production environment’s domain, without the protocol and the port (so if your domain/hostname is https://example.org:3000, you need to write example.org in the organization’s host field).

You can now start your server!

bin/rails s

Visit http://localhost:3000 to see your app running.

Configuration & setup

Decidim comes pre-configured with some sane and safe defaults, but those configurations can be changed through Environment Variables or the Initializer file in your app.

Scheduled tasks

For Decidim to function as expected, there are some background tasks that should be scheduled to be executed regularly. Alternatively you could use whenever gem or the scheduled jobs of your hosting provider. When you are locally testing Decidim for development purposes, you can omit this step or run these tasks manually one by one if you want to test them out.

For production environments, you can configure these tasks with crontab -e. For instance, if you have created your Decidim application at /home/user/decidim_application, you can use the following crontab configuration:

# Remove expired download your data files
0 0 * * * cd /home/user/decidim_application && RAILS_ENV=production bundle exec rake decidim:delete_download_your_data_files

# Compute metrics
1 0 * * * cd /home/user/decidim_application && RAILS_ENV=production bundle exec rake decidim:metrics:all

# Compute open data
2 0 * * * cd /home/user/decidim_application && RAILS_ENV=production bundle exec rake decidim:open_data:export

# Delete old registrations forms
3 0 * * * cd /home/user/decidim_application && RAILS_ENV=production bundle exec rake decidim_meetings:clean_registration_forms

# Generate reminders
4 0 * * * cd /home/user/decidim_application && RAILS_ENV=production bundle exec rake decidim:reminders:all

# Send notification mail digest daily
5 0 * * * cd /home/user/decidim_application && RAILS_ENV=production bundle exec rake decidim:mailers:notifications_digest_daily

# Send notification mail digest weekly on saturdays
5 0 * * 6 cd /home/user/decidim_application && RAILS_ENV=production bundle exec rake decidim:mailers:notifications_digest_weekly

# Change active step in participatory processes
*/15 * * * * cd /home/user/decidim_application && RAILS_ENV=production bundle exec rake decidim_participatory_processes:change_active_step

Further configuration

We also have other guides on how to configure some extra mandatory components:

ActiveJob: For background jobs (like sending emails).
ActiveStorage: For uploading and storing files (like attachments, images, etc.).
Maps: How to enable geocoding for proposals and meetings.
SMTP: For sending emails for account registrations, password reminders, notifications, etc.
Social providers integration: Enable sign up from social networks.
Authorizations: Configure authorizations to verify people’s identities

Deploy

Once you have successfully deployed your applicaton to your favorite platform, you will need to create your System user. You can do this using the following command in your terminal:

bin/rails decidim_system:create_admin

The command asks for an email and a password. For security, the password will not be displayed in the terminal and you need to confirm it by typing it twice.

This will create a system user with the email and password you provided. We recommend using a random password generator and saving it to a password manager, so you have a more secure credentials.

After this, visit the /system panel and login with the email and passwords you just entered and create your organization. Now you are ready to setup your organization and after that you are done! 🎉

What are organizations?

Decidim is a multitenant application that allows you to host multiple different Decidim-based websites within the same system. Organizations are isolated from each other and users in those organizations cannot see any data from other organizations. This allows you to simplify your hosting configuration if you want to use the same codebase for running multiple websites, with each website having their own content and data. To get started with Decidim, you only need to configure one organization.

Note that the system panel admin user you created earlier is also separated from the user accounts on the organization. When you create the organization, you also provided its admin user’s name and email. Decidim will send an email to that address asking that user to create a password for their admin account within the organization. To clarify the difference:

System admin - Manages the organizations on the same platform, does not necessarily have to be involved in any organization
Organization admin - Administers a single organization, i.e. manages its content, sets up processes, adds components, manages user accounts, etc.

You can read the System panel documentation for more info on what are organizations and how they work.

Checklist

There are several things you need to check before making your putting your application on production. See the checklist.

Contributing

We always welcome new contributors of all levels to the project. If you are not confident enough with Ruby or web development you can look for issues labeled good first issue to start contibuting and learning the internals of the project by doing easy jobs.

We also have a developer’s reference that will help you getting started with your environment and our daily commands, routines, etc.

Finally, you can also find other ways of helping us on our contribution guide.