Getting started with 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.
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
wget -O install-decidim.sh https://raw.githubusercontent.com/Platoniq/decidim-install/master/script/install-decidim.sh
chmod +x install-decidim.sh
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.
Administrator for the multitenant
Administrator for the organization
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!
Visit http://localhost:3000 to see your app running.
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
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
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:
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! 🎉
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.
There are several things you need to check before making your putting your application on production. See the checklist.
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.