Manual installation tutorial
In order to develop on decidim, you will need:
Chrome browser and chromedriver.
We are starting with an Ubuntu 22.04.1 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 Ruby on Rails (a good starting point is Getting Started with Ruby on Rails) and have some knowledge on how gems work.
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 the Platoniq guide.
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 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.0.2 rbenv global 3.0.2
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 -sL https://deb.nodesource.com/setup_16.x | sudo -E bash - sudo apt-get install -y nodejs curl -sL https://dl.yarnpkg.com/debian/pubkey.gpg | gpg --dearmor | sudo tee /usr/share/keyrings/yarnkey.gpg >/dev/null echo "deb [signed-by=/usr/share/keyrings/yarnkey.gpg] https://dl.yarnpkg.com/debian stable main" | sudo tee /etc/apt/sources.list.d/yarn.list sudo apt-get update && sudo apt-get install -y 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 cd decidim_application
We recommend that you save it all on Git.
git add . git commit -m "Initial commit. Generated with Decidim https://decidim.org"
5. Configure the database
Modify your secrets (see
config/database.yml). For this you can use figaro, dotenv or rbenv-vars. You
should always be careful of not uploading your plain secrets on git or your version control system. You can also upload the encrypted secrets, using the sekrets gem or if you are on Ruby on Rails greater than 5.1 you can do it natively.
For a development environment, and if you are using rbenv, we strongly recommend you to use the rbenv-vars to facilitate the edition of ENV vars.
First you will need to install the rbenv-vars plugin:
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
Be careful where you put the
.rbenv-vars file, as if you put it in the same folder of your decidim generated application, and if you use a version control system (like
git, which we strongly recommend), then you should ignore this file (ie with the
6. Initializing your app for local development
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 db:seed
This will also create some default data so you can start testing the app, with an administrator account with email email@example.com and password
7. Start your web server
You can now start your server!
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. If you want a working production system then we recommend that you follow the Decidim Install guide by Platoniq.
Other user accounts that you will have in the seeds are:
To participate as a regular user, with email
To manage the Multitenant and being able to log in at
/system, with email
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 db:seed