Skip to content

Getting started

Jump to bottom Edit New page
Jonathan de Faye edited this page May 15, 2020 · 66 revisions

This is a guide for setting up your local Species+ website.

Minimal setup

Prerequisite

  • Make sure you obtain a complete secrets.yml file and .env from a colleague before proceeding. Place the secrets.yml file into your /config folder and your .env in the root folder of your directory.

Step 1: Install dependencies

Before you can install the Species+ application, you will need some tools and libraries installed in your system. Depending on the operating system you're using, these instructions may differ.

This guide is based on a Ubuntu installation.

  1. Git

We use git (GitHub) for source version control.

sudo apt-get install git-core

Check for version to make sure git is installed correctly:

git --version

  1. PostgreSQL v. 9.3

PostgreSQL is the relational store that backs the Species+ database.

sudo apt-get install libpq-dev postgresql-9.3 postgresql-contrib-9.3

Check for version to make sure PostgreSQL is installed correctly:

psql --version

More information on PostgreSQL usage in Species+

  1. Ruby v. 2.0.0

We recommend using rvm to install ruby. We recommend NOT installing system ruby.

Update 04/2020

Please note that there may be an issue when performing a local rvm install of older versions of Ruby (older than ~v2.3) where the OpenSSL version required is no longer hosted resulting in a 404, in which case it's worth trying to install v2.4

For Ubuntu you will need the libssl1.0-dev library: sudo apt install libssl1.0-dev If you have Rbenv installed, you can setup Ruby v2.2.3 with: rbenv install 2.2.3. Based on the .ruby-version file in the root of the project, it should then be using v2.2.3 within the project.

  1. other dependencies
`sudo apt-get install libgmp3-dev`

Step 2: Install the application

  1. Create a local copy of the code repository on your machine:

git clone [email protected]:unepwcmc/SAPI.git

Now change the branch to "develop":

git checkout develop

Please refer to Branching strategy for more information about using branches in Species+.

  1. Install bundler (version 1.17.3, not Bundler 2)

gem install bundler -v 1.17.3 In fact, please check the version specified hopefully within the Gemfile.lock right at the bottom: BUNDLED WITH, and use that (if you haven't already accidentally modified the lock).

  1. Install all the gems

Inside the SAPI directory:

bundle install

If bundle --version isn't 1.17.3, but it is installed - then you can specify the version to use like so: bundle _1.17.3_ install

(this might take a while)

  1. Configure GeoIP

We use a GeoIP mapping to track some user actions. Download the GeoLite Country and GeoLite City free databases from http://dev.maxmind.com/geoip/legacy/geolite/

Create a config file which points to the locations where you saved the databases. A sample config file is provided in config/max_mind.yml

Note you don't have a copy of the 'org_db', which is an optional subscription data set. Just leave the name out, e.g.

  city_db: '/home/agnessa/Data/max_mind_lite/GeoLiteCity.dat'
  country_db: '/home/agnessa/Data/max_mind_lite/GeoIP.dat'
  org_db:

This product includes GeoLite2 data created by MaxMind, available from http://www.maxmind.com.

  1. Configure secrets

cp config/secrets.yml.example config/secrets.yml

  1. Create the database
cp config/database.yml.sample config/database.yml
rake db:create

This will copy the database configuration example file and create a sapi_development database in your PostgreSQL instance.

  1. Populate the database from a dump:

psql -f dump.sql sapi_development

You can obtain a database dump from S3. One way is with Cyberduck.

Credentials can be found for the S3 in the shared LastPass account. There should be a access_key_id and a secret_access_key. Using duck through command line you could download e.g. duck -vd s3:/speciesplus.bkp/PostgreSQL.sql.bz2 ~/Downloads/ -- it will prompt for you for credentials that will be stored for future use.

You may need to extract the SQL before import e.g. bunzip2 PostgreSQL.sql.bz2. Be prepared for a long wait both to extract and to import. Sorry!

  1. Apply any pending migrations

rake db:migrate

Note: don't worry about the verbose output of this command. The standard rails db:migrate task has been extended in SAPI to handle the installation of stored procedures and views. The output is just debug with a list of scripts that get run. As long as there's no error / exception it's all fine.

  1. Start the application server:

rails s

  1. Done! Try the following urls:

Additional setup

Enable background jobs

Background jobs are used for:

  • bulk operations in the Species Admin
  • bulk operations in the Trade Admin
  • generation of CITES Checklist outputs

Please proceed if you need any of the above enabled.

  1. Install Redis

We use redis as a key-value store for the background jobs runner (sidekiq).

sudo apt-get install redis-server

Check for version to make sure redis is installed correctly:

redis-server -v

  1. start redis server:

redis-server

  1. start sidekiq

bundle exec sidekiq

Enable Checklist PDF Outputs

The CITES Checklist is a small Ember.js application that interfaces SAPI and needs to be set up separately. Follow the instructions in https://github.com/unepwcmc/cites-checklist.

To enable PDF outputs generation for the Checklist, it is necessary to install LaTeX.

sudo apt-get install texlive texlive-full texlive-latex-recommended texlive-fonts-recommended

The pdfs are generated by background jobs, so you need sidekiq running as well.

More information on LaTeX usage in Species+

Add a custom footer
Add a custom sidebar
Clone this wiki locally