README.adoc

README

Table of Contents

• 1. Environment
  • 1.1. Running in Development with puma
• 2. Production build war
• 3. Docker

This is the NSL (National Species List) Editor Application developed at the Australian National Botanic Gardens in association with CHAH, the ALA and the IBIS team.

This code is Licensed under the Apache 2 License and we welcome contributions from the taxonomic community.

Please use Github issues for any bug reports.

1. Environment

We run the app under JRuby because Tomcat.

• Ruby version: 2.3.1

• JRuby version: 9.1.5.0

• Rails version: 4.2.7.1

1.1. Running in Development with puma

$ export JRUBY_OPTS='\''-J-Xmx1G -J-XX:MaxPermSize=1G'\''; rbenv local jruby-9.1.5.0; rails s -p 2014
  The signal QUIT is in use by the JVM and will not work correctly on this platform
  => Booting Puma
  => Rails 4.2.7.1 application starting in development on http://localhost:2014
  => Run `rails server -h` for more startup options
  => Ctrl-C to shutdown server
  /Users/gregc/.rbenv/versions/jruby-9.1.5.0/lib/ruby/gems/shared/gems/rack-1.6.4/lib/rack/builder.rb:49: warning: `frozen_string_literal' is ignored after any tokens
  Puma starting in single mode...
  * Version 3.6.0 (jruby 9.1.5.0 - ruby 2.3.1), codename: Sleepy Sunday Serenity
  * Min threads: 0, max threads: 16
  * Environment: development
  * Listening on tcp://localhost:2014
  Use Ctrl-C to stop

• System dependencies

• Configuration

• Set up config files in ~/.nsl

• Here is a sample development config file which lives in ~/.nsl/development/editor-config.rb

  Rails.configuration.services_clientside_root_url = 'http://localhost:8090/nsl/services/'

  Rails.configuration.nsl_links = 'http://localhost:8090/nsl/services/'
  Rails.configuration.nsl_linker = 'http://localhost:8090/nsl/mapper/'
  Rails.configuration.services = 'http://localhost:8090/nsl/services/'

  Rails.configuration.name_services = 'http://localhost:8090/nsl/services/rest/name/apni/'
  Rails.configuration.reference_services = 'http://localhost:8090/nsl/services/rest/reference/apni/'
  Rails.configuration.api_key = 'dev-apni-editor'

  Rails.configuration.ldap_admin_username = "uid=admin,ou=system"
  Rails.configuration.ldap_admin_password = "not the real password"
  Rails.configuration.ldap_base = "dc=com"
  Rails.configuration.ldap_host = 'localhost'
  Rails.configuration.ldap_port = 10389
  Rails.configuration.ldap_users = "ou=Users,dc=example,dc=com"
  Rails.configuration.ldap_groups = "ou=Groups,dc=example,dc=com"

  if ENV['SESSION_KEY_TAG'].nil?
      Rails.configuration.session_key_tag = 'dev'
  else
      Rails.configuration.session_key_tag = ENV['SESSION_KEY_TAG']
  end

  Rails.configuration.mapper_root_url = 'http://localhost:8090/nsl-mapper/'
  Rails.configuration.tree_editor_url = 'http://localhost:8090/nsl/tree-editor/'
  Rails.configuration.mapper_shard = 'apni'
  Rails.configuration.action_mailer.delivery_method =
  Rails.configuration.action_mailer.perform_deliveries =
  Rails.configuration.action_mailer.raise_delivery_errors =

  Rails.configuration.action_mailer.smtp_settings =

  Rails.configuration.environment = 'development'
  Rails.configuration.draft_instances = true

  # ICZN recognises changed combination names, irrelevant to ICN
  Rails.configuration.allow_name_changed_combination = false
  # ICZN not interested in the full author history of names
  Rails.configuration.allow_name_ex_base_author = true
  Rails.configuration.allow_name_base_author = true
  Rails.configuration.allow_name_ex_author = true
  Rails.configuration.allow_name_sanctioning_author = true
  # ICZN uses name.published year, irrelevant to ICN
  Rails.configuration.allow_name_published_year = false

  Rails.configuration.offer_feedback_link = false
  Rails.configuration.feedback_script = 'not the real script'

  Rails.configuration.nsl_host_and_port = 'http://localhost:8090'

  Rails.configuration.show_new_search_link = true
  Rails.configuration.search_address = 'http://localhost:2006'
  Rails.configuration.show_timings = true

• Database creation

• Database initialization

• Set up LDAP

• How to run the test suite

  rake test:controllers
  rake test:models

  Integration tests are very slow and neglected sadly.

• Services (job queues, cache servers, search engines, etc.)

• Deployment instructions

  create user webapni;
  grant select, insert, update, delete on author to webapni;
  etc

  grant select on nsl_global_seq to webapni;

  grant select on reference_vw to webapni;

• Code is rubocopped with these exceptions:

  AllCops:
    Exclude:
      - 'db/**/*'
  Style/TrailingCommaInLiteral:
    Enabled: false
  Style/VariableNumber:
    Enabled: false
  StringLiterals:
    EnforcedStyle: double_quotes
    Enabled: true
  Style/ClassAndModuleChildren:
    Enabled: false

2. Production build war

Run the build.sh bash script to build a war file using JRuby and Warbler. The build script will download a version of JRuby and cache it in the bin directory for use in the build. You just need to supply a version of Java.

If you don’t have Java 8 installed use SDKMan and try sdk install java 1.8.0-adpt for example to install a JDK.

build.sh will create a production nsl-editor.war file in the project directory ready to use in tomcat or Docker

3. Docker

You can run the editor in Docker using the Dockerfile. The following will build a docker image from the war file and expose it on port 8080 on your machine.

docker build -t nsl-editor .
&& docker run
-p 0.0.0.0:8080:8080
-v $HOME/.nsl:/etc/nsl:ro
--env EDITOR_CONFIG_FILE=/etc/nsl/editor-config.rb
--env EDITOR_CONFIGDB_FILE=/etc/nsl/editor-database.yml
--env SECRET_KEY_BASE=A-random-key-generated-by-a-rake-task-that-is-very-very-very-long
nsl-editor

The dockerize.sh will build tag and push the docker image to dockerhub, but currently uses my personal dockerhub account.