Development App

In order to start developing you will need what is called a development_app. This is nearly the same as a new Decidim app (that you can create with decidim app_name) but with a Gemfile pre-configured for local development and some other small config modifications.

We recommend that you first have a working Decidim app so that you have fulfilled all the necessary system and services requirements, like having a working Ruby installation, PostgreSQL, Node.JS, etc.

You will need to configure the PostgreSQL database before anything. For this,

  1. Configure postgresql with a super-user. For instance, for a user called decidim_development_app_user with password changeme, it’d be:

sudo -u postgres psql -c "CREATE USER decidim_development_app_user WITH SUPERUSER CREATEDB NOCREATEROLE PASSWORD 'changeme'"

  1. Save the database configuration in your environment variables configuration. If you have followed the Decidim installation manual, then you should have a working rbenv-vars in your environment:

echo "DATABASE_USERNAME=decidim_development_app_user" >> ~/.rbenv-vars
echo "DATABASE_PASSWORD=changeme" >> ~/.rbenv-vars

Of course you should change the password before anything.

  1. Then you can create a development_app from inside the project’s root folder with the command:

git clone https://github.com/decidim/decidim.git
cd decidim
bundle install
bin/rake development_app

A development_app/ entry appears in the .gitignore file, so you do not have to worry about committing the development app by mistake.

On creation, these steps are automatically invoked by the generator:

  • create a config/database.yml

  • bundle install

  • bin/rails decidim:upgrade

  • bin/rails db:create

  • bin/rails db:migrate

  • bin/rails assets:precompile

  • bin/rails db:seed

Mind that if everything went well you should not need to run these commands manually.

If the default database.yml does not suit your needs you can always configure it at your will and run these steps manually, although we recommend that you make the database configurations with environment variables (ENV VARs) so it is easy for you to regenerate the database.

The last command will set your database and add some example data (called "seed data") so that you can start trying Decidim. We do not recommend using seed data for production environments, but it is useful for local development and staging environments.

Once the app is created you are ready to start the server:

  • bin/dev

This script starts the rails web server and also the webpack dev server, so you do not have to worry about starting them separately.

Migrations

When creating new migrations in Decidim’s modules, you will need to "apply" this migrations to your development_app. The way to do this is by copying the migration from your module into the db/migrate dir of your development_app. Luckily we already have a script that automates this: it copies all missing migrations in development_app/db/migrate. The command is:

bin/rails decidim:upgrade

Anyway we recommend re-creating your development_app every once in a while.

Updating from develop

We recommend that you periodically update your codebase with the last changes from the main repository. For this, you will need to follow these instructions:

git pull origin develop
bin/rails decidim:upgrade
bin/rails db:migrate

And restart your rails server (with Ctrl+C to stop it).

Re-creating the development_app

If you are working with old branches or there were multiple changes in develop, you will need to re-create your development_app.

bin/rake development_app