The Gobierto Developer Hub

Welcome to the Gobierto developer hub. You'll find comprehensive guides and documentation to help you start working with Gobierto as quickly as possible, as well as support if you get stuck. Let's jump right in!


Development environment


This guide will help you to setup Gobierto and its dependencies in your local environment machine:

  • This guide assumes you are using macOS and have Homebrew installed.
  • The main dependencies are: postgres, redis, elasticsearch, node.js and yarn

Download Gobierto

First, clone Gobierto git repository in your working directory:

git clone [email protected]:PopulateTools/gobierto.git

Gobierto uses environment variables for configuration. To setup the environments variables file, use the example file and copy it to the .env file:

$ cp .env.example .env

Gobierto will work with the example values by default. You can learn more about the variables in the document environment variables description.


Gobierto is a Ruby on Rails application so you need to install Ruby first. You can check here which version of Ruby is the current one.

To install Ruby we recommend a Ruby version manager, such as rvm or Rbenv (our preferred choice). After installing the Ruby version manager, install the gem bundler: gem install bundler and run bundle install to install the required gems. After that you will be ready for the next steps.

If you chose rbenv you should install a plugin to use environment variables:

  1. Check you have rbenv-vars plugin installed
  2. Symlink .env to .rbenv-vars file. Yo can do this by running:
$ ln -s .env .rbenv-vars
  1. Verify variables are properly configured by running rbenv vars. You should see something like:
export INTEGRATION_DEBUG='false'
export TEST_LOG_LEVEL='debug'
export RACK_ENV='development'
export RAILS_ENV='development'
export HOST='gobierto.test'


Gobierto uses Postgres as the main database. We recommend version 12, but Gobierto is compatible with >= 9.6. If you have Postgres installed you can skip these steps and follow in Configure Postgres.

brew install postgres

Once installed, we need to initialize it:

initdb /usr/local/var/postgres

Now we're going to configure some things related to the default user. First we start the postgres server with:

postgres -D /usr/local/var/postgres

At this point we're supposed to have postgres correctly installed and a default user will automatically be created (whose name will match our username).

Configure Postgres

Now fill config/database.yml (you can copy it from config/database.yml.example) with the corresponding database credentials. We use some environment vars for convenience:

  • PG_USERNAME: your username
  • PG_PASSWORD: your database password
  • PG_HOST: localhost for development (and you can remove the URL).

Now run the following command to create the database and load some seeds:

bin/rails db:setup


Gobierto uses Redis for managing background jobs with Sidekiq. Install Redis with:

brew install redis

Now start the redis server using a configuration file:

redis-server /usr/local/etc/redis.conf
  • The redis server will start to listen to connections on

Complete the REDIS_URL line inside the .env file with the following value:



Gobierto uses ElasticSearch to store budgets data. If you are not going to use the budgets module you can skip this step.

Install elasticsearch 2.4 (Gobierto doesn't support newer versions yet) with:

brew install [email protected]

Then you can start it by typing:

brew services start [email protected]

Complete the ELASTICSEARCH_URL line inside the .env file with the following value:


Node.js and Yarn

Node.js and Yarn are dependencies to run the javascript assets packer. Gobierto uses Webpack to package javascripts.

Recommended versions are:

  • Node.js >= 12.10.0
  • Yarn >= 1.17.0

You can install both using Homebrew:

brew install nodejs yarn

You can now install the dependencies with:

yarn install

Development top-level domain and port proxying

Gobierto is a multi-tenant application, designed to serve multiple tenants from the same instance of the application. A tenant is a group of users who share a common access with specific privileges to the software instance. In our case these tenants are the different cities using Gobierto.

When running a single Gobierto rails application, you'll be able to access each of the available tenants throught a custom URL. The easiest way to deal with this is to use puma-dev's Port Proxying feature.

To install puma-dev run

brew install puma/puma/puma-dev
# and configure it with:
sudo puma-dev -setup
puma-dev -install

After installing it you'll need to reboot your computer for the DNS resolver to work properly. puma-dev will now boot on launch.

Once puma-dev is installed, you have to configure it to work with Gobierto:

ln -s ~/path/to/gobierto .puma-dev/gobierto

The seeds provided for development, as explained here, have two available tenants: one for the city of Madrid and one for Santander.

The application server should be queried through the top-level domain .gobierto.test. Each of the tenants are accessible on their corresponding subdomais:

Note: If you have ever had pow installed on your computer it may cause some issues with puma-dev when running as a daemon. Everything will seem properly configured, but if you try to access the addresses mentioned above by curl or your browser they won't be able to resolve.

If that is the case, and you have already tried to uninstall pow, there is a known issue with the uninstall script of pow that leaves some configuration behind. Our recommendation is to go through (the mentioned script)[http://get.pow.cx/uninstall.sh] steps one by one on your terminal.

Open Gobierto

Now you can start using Gobierto! Notice that there's no need to start the common rails server because puma runs in background:

  1. Start webpack dev server with: bin/webpack-dev-server
  2. Go to http://madrid.gobierto.test to see a demo site
  3. Go to the administrator and configure the site: http://madrid.gobierto.test/admin

Appendix 1 - Integration tests drivers

Currently we're migrating from PhantomJS to Chromedriver, so you need to install both of them:

brew install phantomjs
brew cask install chromedriver

Run the tests!

Now you can run the tests with:

  • NOTE: it is not enough to run bin/rails test since the test script contains a few more necessary steps.

Appendix 2 - Mailcatcher

To use MailCatcher, just run $ mailcatcher command and follow the instructions printed in the terminal.

Appendix 3 - Using xip.io to develop in mobile devices

xip.io is a magical DNS that allows us to expose our local server to external devices, such as other computers or mobile devices. It's very useful to check the dev server in a mobile.

Just follow the following steps:

  1. Figure out your LAN IP, in your Network preferences or just by doing in the shell: ifconfig | grep 192. Let's say it's, it means that Gobierto will be visible in *.
  2. Log into your Gobierto instance and edit the site you want to expose, by updating the domain to something like madrid.gobierto.test.
bin/rails c
site = Site.find_by domain: "madrid.gobierto.test"
site.domain = "madrid.gobierto.test."
  1. Stop the rails server and start it again with a new parameter to bind it to any address: rails s -b
  2. That's all, now you can visit http://madrid.gobierto.test. in any device

Updated 3 months ago

What's Next

Learn how to configure properly environment variables and to administrate a site:

Environment variables overview
Administración de un sitio

Development environment

Suggested Edits are limited on API Reference Pages

You can only suggest edits to Markdown body content, but not to the API spec.