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
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
$ 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.
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:
- Check you have rbenv-vars plugin installed
.rbenv-varsfile. Yo can do this by running:
$ ln -s .env .rbenv-vars
- 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' ...
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:
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).
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:
Gobierto uses Redis for managing background jobs with Sidekiq. Install Redis with:
brew install redis
Now start the redis server using a configuration file:
- The redis server will start to listen to connections on
REDIS_URL line inside the
.env file with the following value:
- Useful resources - Redis setup
Gobierto uses ElasticSearch to store budgets data. If you are not going to use the budgets module you can skip this step.
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]
ELASTICSEARCH_URL line inside the
.env file with the following value:
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:
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.
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.
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.
Now you can start using Gobierto! Notice that there's no need to start the common
rails server because puma runs in background:
- Start webpack dev server with: bin/webpack-dev-server
- Go to http://madrid.gobierto.test to see a demo site
- Go to the administrator and configure the site: http://madrid.gobierto.test/admin
- Admin credentials:
- User credentials. Check Development accounts (users and admins)
Currently we're migrating from PhantomJS to Chromedriver, so you need to install both of them:
brew install phantomjs brew cask install chromedriver
Now you can run the tests with:
- NOTE: it is not enough to run
bin/rails testsince the test script contains a few more necessary steps.
MailCatcher, just run
$ mailcatcher command and follow the instructions printed in the terminal.
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:
- 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
- Log into your Gobierto instance and edit the site you want to expose, by updating the domain to something like
bin/rails c site = Site.find_by domain: "madrid.gobierto.test" site.domain = "madrid.gobierto.test.192.168.1.41.xip.io" site.save!
- 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
- That's all, now you can visit http://madrid.gobierto.test.192.168.1.41.xip.io:3000/ in any device
Updated 9 days ago