Manual installation tutorial

In order to develop on decidim, you will need:

  • Git 2.34+

  • PostgreSQL 17.4+

  • Ruby 3.3.0

  • NodeJS 22.14.x

  • Npm 10.9.x

  • ImageMagick

  • Chrome browser and chromedriver (if you need to run specs/tests)

The compatibility between the different versions of the components is the following:

Decidim version Ruby version Node version Status

develop

3.3.4

22.14.x

Unreleased

v0.30

3.3.4

18.17.x

Bug fixes and security updates

v0.29

3.2.2

18.17.x

Bug fixes and security updates

v0.28

3.1.1

18.17.x

Not maintained

v0.27

3.0.2

16.18.x

Security updates

v0.26

2.7.5+

16.9.x

Not maintained

We are starting with an Ubuntu 24.04.3 LTS. This is an opinionated guide, so you are free to use the technology that you are most comfortable. If you have any doubts and you are blocked you can go and ask on our Matrix.org chat room for developers.

We recommend to have at least some basic proficiency in GNU/Linux (i.e. how to use the command-line, packages, etc), networking knowledge, server administration, development in general, and some basic knowledge about software package managers. It would be great to have Ruby on Rails development basics (a good starting point is Getting Started with Ruby on Rails) and have some knowledge on how package libraries are working (we use bundler for handling ruby packages, and npm/yarn for handling javascript).

In this guide, we will see how to install rbenv, PostgreSQL, Node.js and, Decidim, and how to configure everything together for a development environment. Mind that if you want to make a production deployment with real users this guide is not enough, you should configure a web server (like nginx), backups, monitoring, etc. This is out of the scope of this guide, but you can follow any Ruby on Rails guide on how to configure it for production or use a service like Render, Fly.io, Heroku, etc.

1. Installing rbenv

First, we are going to install rbenv, for managing various ruby versions. You could also use rvm or asdf as alternatives on this step.

sudo apt update
sudo apt install -y build-essential curl git libssl-dev zlib1g-dev libffi-dev libyaml-dev
git clone https://github.com/rbenv/rbenv.git ~/.rbenv
echo 'export PATH="$HOME/.rbenv/bin:$PATH"' >> ~/.bashrc
echo 'eval "$(rbenv init -)"' >> ~/.bashrc
source ~/.bashrc
git clone https://github.com/rbenv/ruby-build.git ~/.rbenv/plugins/ruby-build
rbenv install 3.3.0
rbenv global 3.3.0

2. Installing PostgreSQL

Now we are going to install PostgreSQL for the database:

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 (in this example is "thepassword") and save it somewhere to configure it later with the application.

3. Installing Node.js

An important component for Decidim is Node.js and Yarn. With this commands you will install them:

curl -o- https://raw.githubusercontent.com/nvm-sh/nvm/v0.40.3/install.sh | bash
source "$HOME/.nvm/nvm.sh"
nvm install 24
npm install -g yarn

4. Installing Decidim

Next, we need to install the decidim gem with its dependencies:

sudo apt install -y libicu-dev imagemagick
gem install decidim

Then we can create an application with the decidim executable, where decidim_application is your application name (ie DecidimBarcelona):

decidim decidim_application

5. Configure the database

For configuring the database and other parts of Decidim, we use Environment variables. We recommend using rbenv-vars.

Be careful with your .rbenv-vars file, as if you put it in the same folder of your decidim generated application you could publish it without you noticing and there will be secrets there. We strongly recommend adding it to other directory

For installing rbenv-vars:

git clone https://github.com/rbenv/rbenv-vars.git "$(rbenv root)"/plugins/rbenv-vars

Then, in any folder above your decidim generated application, you need to create a file named .rbenv-vars and put your variables there:

cat << EOF > .rbenv-vars
DATABASE_HOST=localhost
DATABASE_USERNAME=decidim_app
DATABASE_PASSWORD=thepassword
EOF

6. Initializing your app for local development

At this point we recommend that you save it all on Git.

cd decidim_application
git add .
git commit -m "Initial commit. Generated with Decidim https://decidim.org"

Please refer to Empty database installation section if you want to setup your instance with an empty database (without any seeds).

We should now create your database. For a first local installation, we recommend to start with some example contents (also known as seeds).

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

This will also create some default data so you can start testing the app, with an administrator account with email admin@example.org and password decidim123456789

7. Start your web server

You can now start your server!

bin/dev

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

With these steps you would only have an initial installation for trying Decidim, but it still needs lots of things to take in account.

Extra notes

Other user accounts that you will have in the seeds are:

  • To participate as a regular user, with email user@example.org and password decidim123456789.

  • To manage the Multitenant and being able to log in at /system, with email system@example.org and password decidim123456789.

The seed data will not be created in production environments, if you still want to do it (for instance, for a Demo or Staging server), run:

SEED=true rails assets:precompile db:seed