Difference between revisions of "Virtual Appliance FAQ"

From NCBO Wiki
Jump to navigation Jump to search
Line 19: Line 19:
   config.smtp_port              = 25
   config.smtp_port              = 25
   config.smtp_auth_type        = :none # :none, :plain, :login, :cram_md5
   config.smtp_auth_type        = :none # :none, :plain, :login, :cram_md5
  config.smtp_user              = "username" # only used if auth_type is not :none
  config.smtp_password          = "password" # only used if auth_type is not :none
   config.smtp_domain            = "example.org"
   config.smtp_domain            = "example.org"
Once you have changed your settings, you will need to restart the server by running the command <code>/sbin/service unicorn restart</code>
= Ontology Management =
= Ontology Management =

Revision as of 10:49, 17 September 2014


This FAQ now covers the NCBO Virtual Appliance v2.0. The FAQ for v1.0 is available in the archive


How can I enable emails for lost passwords, notes, and ontology processing?

Emails are sent via the ontologies_api project on the Appliance. You need to provide a valid mail server (smtp) configuration. The configuration should be provided in the /srv/ncbo/ontologies_api/current/config/environments/production.rb file.

Here are the available settings:

 config.enable_notifications   = true # Set to 'true' to send emails
 config.email_sender           = "admin@example.org" # Default sender for emails
 config.email_disable_override = true # If this is set to 'false', all emails will be sent to the email configured in the 'email_override' setting
 config.email_override         = "admin@example.org"
 config.smtp_host              = "smtp.example.org"
 config.smtp_port              = 25
 config.smtp_auth_type         = :none # :none, :plain, :login, :cram_md5
 config.smtp_user              = "username" # only used if auth_type is not :none
 config.smtp_password          = "password" # only used if auth_type is not :none
 config.smtp_domain            = "example.org"

Once you have changed your settings, you will need to restart the server by running the command /sbin/service unicorn restart

Ontology Management

How do I add or change categories or groups?

There is currently no UI administrator interface (though this will likely be added in future versions). Categories and groups can be added using a console after logging into the Appliance as the root user.

# from the bash shell:
cd /srv/ncbo/ncbo_cron
bin/ncbo_cron --console
# once in the ruby console:
category = LinkedData::Models::Category.new
category.name = "My Category"
category.acronym = "MY_CAT"
group = LinkedData::Models::Group.new
group.name = "My Group"
group.acronym = "MY_GRP"

How do I delete an ontology?

Deleting can be done using a console after logging into the Appliance as the root user.

# from the bash shell:
cd /srv/ncbo/ncbo_cron
bin/ncbo_cron --console
# once in the ruby console:
ontology = LinkedData::Models::Ontology.find("MY_ONTOLOGY_ACRONYM").first

How can I migrate ontologies from BioPortal or previous NCBO Virtual Appliance versions into a new Appliance?

Programmatic migrations are currently unsupported. Ontologies can be manually downloaded and added using the Web UI.

Ontology Parsing

When are new ontologies parsed?

The ncbo_cron project uses a scheduler to run a process that collects new ontology submissions and parses them, adds them to the search index, calculates metrics, and processes them for use with the annotator. You can also parse ontologies manually.

How do I manually parse an ontology?

To manually parse an ontology, you will need to interact with the code using the console:

# from the bash shell:
cd /srv/ncbo/ncbo_cron
bin/ncbo_cron --console
# once in the ruby console:
ontology = LinkedData::Models::Ontology.find("MY_ACRONYM").first
submission = ontology.latest_submission(status: :any)
logger = Logger.new(STDOUT)
# make available in annotator
annotator = Annotator::Models::NcboAnnotator.new
annotator.create_term_cache_for_submission(logger, submission)

How can I process a UMLS ontology?

UMLS ontologies can be processed to work with our system by converting them to RDF. There is no automated way to do this and you must have your own UMLS MySQL installation and a OSX/Linux/Unix machine with 8GB+ of RAM in order for the conversion process to work. The scripts to convert UMLS to RDF are available on Github.

Once you have converted UMLS to RDF, you will get Turtle (.ttl) files that can be uploaded using the BioPortal Web UI. Please select UMLS as the format for these ontologies.

How do I know if an ontology has parsed?

The BioPortal Web UI will cache information about ontologies for 60 seconds. After parsing is complete, just refresh the ontology summary page to see the status for the most recent submission listed under the "Submissions" table.

In addition, you can look at the REST service directly, which will always give you the most updated information. To do this, visit the following URL:

Is there a log file for parsing?

Parsing progress is logged in the ontology submission repository folder: /srv/ncbo/repository/{ontology acronym}/{submission id}

Web User Interface

How can I clear the memcached-based UI cache?

  • If you are logged in as the admin user, simply visit http://example/admin and click the "Flush Memcache" button. There should be a response indicating success or failure.

How can I use widgets with my Virtual Appliance?

In addition to the existing instructions, you must define an additional Javascript variable in order to have the widgets communicate with your instance of the Virtual Appliance.

 var BP_SEARCH_SERVER = "http://{your_appliance_ip_or_domain_name}";

Replace the '{your_appliance_ip_or_domain_name}' text with the IP address or domain name that's assigned to your Virtual Appliance.

Virtualization Environments

How can I use the OVF image with my virtualization software?
(VMware, VirtualBox, KVM, Xen, etc)


You can use VMware's ovftool to convert the appliance to work with your VMware product. For example, to convert the appliance for use in VMware Player or Workstation, you would run the command:

ovftool ncbo-appliance.ovf ncbo-appliance.vmx


VirtualBox supports importing OVF images directly. Simply start your VirtualBox software, then select File->Import Appliance and select the OVF file included in the NCBO Virtual Appliance download.


First, convert the OVF to VMX format as mentioned in the VMware section above.

Next, ensure that the kvm-qemu-img RPM (or qemu-kvm DEB) is installed. Then, convert the [new] VMDKs (from the VMX conversion step) to raw disk images via the following command:

for disk in `ls -1 *.vmdk`; do diskbase=`basename $disk .vmdk`; qemu-img convert -O raw ${diskbase}.vmdk ${diskbase}.img; done

Create /etc/libvirt/qemu/ncbo-appliance.xml with the following contents:

<domain type='kvm'>
    <type arch='x86_64' machine='rhel5.4.0'>hvm</type>
    <boot dev='hd'/>
  <clock offset='utc'>
    <timer name='pit' tickpolicy='delay'/>
    <disk type='file' device='disk'>
      <driver name='qemu' type='raw'/>
      <source file='/var/lib/libvirt/images/ncbo-appliance/ncbo-appliance-disk1.img'/>
      <target dev='hda' bus='ide'/>
      <address type='drive' controller='0' bus='0' unit='0'/>
    <disk type='file' device='disk'>
      <driver name='qemu' type='raw'/>
      <source file='/var/lib/libvirt/images/ncbo-appliance/ncbo-appliance-disk2.img'/>
      <target dev='hdb' bus='ide'/>
      <address type='drive' controller='0' bus='0' unit='1'/>
    <controller type='ide' index='0'/>
    <interface type='network'>
      <source network='default'/>
      <model type='virtio'/>
    <serial type='pty'>
      <target port='0'/>
    <console type='pty'>
      <target port='0'/>
    <input type='mouse' bus='ps2'/>
    <graphics type='vnc' port='-1' autoport='yes' keymap='en-us'/>
      <model type='cirrus' vram='9216' heads='1'/>

Finally, make any necessary edits to the above file, and run:

virsh start ncbo-appliance


First, convert the VMDKs to raw disk images as mentioned in the KVM section above.

Create /etc/xen/ncbo-appliance.cfg with the following contents:

name = "ncbo-appliance"
memory = 4096
vcpus = 2
builder = "hvm"
kernel = "/usr/lib/xen/boot/hvmloader"
boot = "c"
pae = 1
acpi = 1
apic = 1
localtime = 0
on_poweroff = "destroy"
on_reboot = "destroy"
on_crash = "destroy"
device_model = "/usr/lib64/xen/bin/qemu-dm"
sdl = 0
vnc = 1
vncunused = 1
keymap = "en-us"
disk = [ "file:/var/lib/xen/images/ncbo-appliance/ncbo-appliance-disk1.img,hda,w", "file:/var/lib/xen/images/ncbo-appliance/ncbo-appliance-disk2.img,hdb,w" ]
vif = [ "bridge=xenbr0,script=vif-bridge,vifname=vif41.0" ]
parallel = "none"
serial = "pty"

Finally, make any necessary edits to the above file, and run:

xm create ncbo-appliance

How can I use the Appliance on Amazon EC2?

  • Click on Launch Instances which will bring up Launch Instance Wizard with multiple tabs.
  • 1. Choose AMI:
    • Select Community AMIs and search of “NCBO Appliance” and choose the latest version
  • 2. Choose Instance Type Tab
    • Instance Type = General Purpose m1.xlarge (or any other type with at least 4 vCPUs and ~8 GB of RAM)
  • 3. Configure Instance Tab
    • Availability Zone = No preference
    • Termination Protection = Prevention against accidental termination
    • Shutdown Behavior = Stop
  • 5. Instance Tags:
    • Name = Name this instance something meaningful
  • 6. Configure Security Group
    • Choose (you may need to create one first) a Security Group that has ports 22, 80, and 8082 open. It is recommended that you only allow the networks you need. We accept no responsibility/liability for machines getting compromised.

Click "Launch" You will have to create or choose an existing Key Pairs or Create a Key Pair.

  • Click on Instances (left hand side of the screen):
    • Once the instance State has changed from Pending to Running and Status Checks is “2/2 checks passed”, login to the instance via the public hostname provided.
    • Now you can SSH into the machine using your key-pair and ec2-user as the user name:
      • ssh -i yourkey_pair ec2-user@{amazon public domain name}
    • The domain name can be retrieved by clicking on the instance and looking at the details that appear at the bottom of the screen. It should look similar to this but with a different set of numbers in the subdomain: ec2-10-0-0-1.us-west-1.compute.amazonaws.com