Getting started

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

Minimal setup

Prerequisite

• You can obtain the .env file contents required for this project on the Shared-Informatics Development Environments LastPass searchable by SAPI Development Environment
• You will also need an up-to-date SQL dump to restore the database. 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 under the name Species+ S3 access keys. Using duck through command line you could download e.g. duck -vd s3:/speciesplus.bkp/Daily/db/new_db_server/sapi_website_db_daily/2020.05.25.00.00.02/sapi_website_db_daily.tar ~/Downloads/ -- it will prompt for you for credentials that should be stored for future use. You can then extract the file in two steps, first untar e.g. tar -vxf sapi_website_db_daily.tar then unzip the SQL within e.g. bzip2 -d sapi_website_db_daily/databases/PostgreSQL.sql.bz2

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. For MacOs jump to - MacOS users

1. GitYou 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.

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

2. 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+

3. 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.

Update 11/2021

Ruby v. 2.3.1

4. 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+.

2. 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).

3. 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)

3. 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: '/usr/share/max_mind_lite/GeoLiteCity.dat'
  country_db: '/usr/share/max_mind_lite/GeoIP.dat'
  org_db:

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

It does appear that .dat files are no longer available. See also here. The impact this has on the project is unknown to this author - mmdb files may need to be converted to dat before use.

3. Configure secrets

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

4. 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.

5. Populate the database from a dump:

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!

psql -f dump.sql sapi_development

You will likely discover that this does not work if the database has not been created so let's do that:

sudo -u postgres createdb sapi_development

If you have any issues, you can drop the DB with the dropdb variation of the above command.

6. 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.

7. Start the application server:

rails s

8. Done! Try the following urls:

• http://localhost:3000 - Species+
• http://localhost:3000/admin - Species Admin
• http://localhost:3000/cites_trade - CITES Trade
• http://localhost:3000/trade - Trade Admin

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

See this very helpful guide.

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

sudo apt-get install redis-server

You can set it up as a background service by modifying the config sudo nano /etc/redis/redis.conf and change supervised no to supervised systemd then save & exit and sudo systemctl restart redis.service

Check for version to make sure redis is installed correctly:

redis-server -v

2. start redis server:

redis-server

3. 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+

MacOS users

Prerequisites:

Xcode 13.4

1. install both Xcode and CLI Tools from apple - https://developer.apple.com/download/all/?q=xcode%2013.4

2. Postgres 11:

brew install postgresql@11

brew services start postgresql@11

3. To run multiple postgres versions follow this: https://www.mendelowski.com/docs/postgresql/running-multiple-versions-on-macos/

4. The port - needs to be as specified in config/databas.yml

pg_createcluster 11 main -p 5432

and

pg_lsclusters 11 main start

5. Might need to create the db manually:

if there are errors on bundle exec rake db:create saying that there is no

to login to postgres:

psql

if no error move to 6.

if error - database “someusername” (btw. someusername is your mac username) does not exist create it:

createdb someusername

sudo -i -u someusername

Then move to 6.

6. in postgres cli:

\du

check the output - should list the someusername db (here my user name - dagmarakukla)

CREATE DATABASE sapi_development WITH OWNER postgres;

and exit: \q

Now you can go back to the top of the page and follow the set up excluding the point 2. PostgreSQL v. 9.3