Guides

Development environment

Suggest Edits

Overview

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.

Ruby

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 INTEGRATION_INSPECTOR='false'
export TEST_LOG_LEVEL='debug'
export RACK_ENV='development'
export RAILS_ENV='development'
export HOST='gobierto.test'
...

Postgres

Gobierto uses Postgres as the main database. It requires version >= 12. 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

Redis

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 127.0.0.1:6379

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

REDIS_SIDEKIQ_URL=redis://localhost:6379/0
REDIS_SIDEKIQ_PASSWORD=
REDIS_SIDEKIQ_CA_FILE=
REDIS_CACHE_URL=redis://localhost:6379/1
REDIS_CACHE_PASSWORD=
REDIS_CACHE_CA_FILE=

ElasticSearch

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:

ELASTICSEARCH_URL=http://localhost:9200

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 >= 18.x
  • Yarn >= 1.17.0

You can install both using Homebrew:

brew install nodejs yarn

You can now install the dependencies with:

yarn install

In case of node > 16 ensure you have set the environment variable NODE_OPTIONS=--openssl-legacy-provider

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.

Debugging backend

We're using pry gem.

In order to stop at the breakpoints you set, just place the keyword binding.pry within the code.

It's advisable to run the frontend (yarn build --watch) and the backend (bin/rails server) in different tabs to take advantage of the rails console environment. Otherwise, both outputs are mixed and it's sort of confusing.

mount symbolic links for gobierto_engines folder

there are threee rails engines that are required:

  • custom-fields-data-grid-plugins
  • custom-fields-progress-plugins
  • custom-fields-table-plugins
# bash

echo 'export DEV_DIR="~/populate-tools"' >> ~/.bash_profile
source ~/.bash_profile

tree -L 1
. # ~/populate-tools
├── ...
├── ...
└── gobierto

cd vendor/gobierto_engines/custom-fields-data-grid-plugin/
script/setup.sh

cd vendor/gobierto_engines/custom-fields-progress-plugin/
script/setup.sh

cd vendor/gobierto_engines/custom-fields-table-plugin/
script/setup.sh

check if works with

ls gobierto/app/javascript/packs/custom_fields_* -lp

app/javascript/packs/custom_fields_data_grid_plugin.js -> ~/populate-tools/gobierto/vendor/gobierto_engines/custom-fields-data-grid-plugin/app/javascripts/packs/custom_fields_data_grid_plugin.js
app/javascript/packs/custom_fields_progress_plugin.js -> ~/populate-tools/gobierto/vendor/gobierto_engines/custom-fields-progress-plugin/app/javascripts/packs/custom_fields_progress_plugin.js
app/javascript/packs/custom_fields_table_plugin.js -> ~/populate-tools/gobierto/vendor/gobierto_engines/custom-fields-table-plugin/app/javascripts/packs/custom_fields_table_plugin.js


tree -L 1 vendor/gobierto_engines/custom-fields-data-grid-plugin/

vendor/gobierto_engines/custom-fields-data-grid-plugin/
├── app
├── config
├── lib
├── node_modules -> ~/populate-tools/gobierto/node_modules
├── README.md
├── script
├── test
└── typescript

tree -L 1 vendor/gobierto_engines/custom-fields-progress-plugin/
vendor/gobierto_engines/custom-fields-progress-plugin/
├── app
├── config
├── lib
├── node_modules -> ~/populate-tools/gobierto/node_modules
├── README.md
├── script
├── test
└── typescript

 tree -L 1 vendor/gobierto_engines/custom-fields-table-plugin/
vendor/gobierto_engines/custom-fields-table-plugin/
├── app
├── config
├── lib
├── node_modules -> ~/populate-tools/gobierto/node_modules
├── README.md
├── script
└── test

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:

./script/test   # elastic search test
bin/rails test  # test
  • 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 192.168.1.41, it means that Gobierto will be visible in *.192.168.1.41.xip.io
  2. Log into your Gobierto instance and edit the site you want to expose, by updating the domain to something like madrid.gobierto.test.192.168.1.41.xip.io:
bin/rails c
site = Site.find_by domain: "madrid.gobierto.test"
site.domain = "madrid.gobierto.test.192.168.1.41.xip.io"
site.save!
  1. Stop the rails server and start it again with a new parameter to bind it to any address: rails s -b 0.0.0.0
  2. That's all, now you can visit http://madrid.gobierto.test.192.168.1.41.xip.io:3000/ in any device

Appendix 4 - Webpack configuration files

Each environment owns its settings file, located at config/webpack. Any webpack plugin/loader/config could be added or removed from these files, in addition to the @rails/webpacker defaults.

The development environment enables two specific plugins:

They must be called on demand using environment variables. The first one will open the browser at http://127.0.0.1:8888/ once the application is up. The second one comes up at the compilation time, displaying how long did it take to compile and bundle the assets.

The test environment appends a particular setting for the Terser plugin (assets minification)

Updated 29 days ago

What’s Next

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