Installation

Installation

This part of the wiki explains how to install the BioCASe Provider Software. Depending on your skills, it should take between 15 and 60 minutes. If you’re a beginner, please read the Beginner’s Guide first.

Requirements and Considerations

Before installing, please make sure that the system you’re intending to install the BPS on meets the following requirements (If you find out one of these items is not met, please ask your system administrator for help, read the FAQ or get in contact with the BioCASe Team.):

1. You have administrative privileges on this machine, i.e. the user rights to install new software packages.
2. It is accessible from outside your institution. This means it either needs to be outside any institutional firewall or, more likely, the HTTP port is open for an existing firewall.
3. A direct connection can be established from this machine to the database to be published – either because there’s no firewall in between, or the port used by the DBMS is open (e. g. 3306 for MySQL).

In addition to the regular installation (see section below), you can install BioCASe from a Docker image. Docker is an operating-system-level virtualization software that allows easy software deployment in so-called containers. If you don't know yet what Docker is, you should read the Get Started Guide. If you're famliar with Docker, we'd suggest to use the Docker path for installing BioCASe - read more in section Installing from a Docker image below.

Regular BioCASe Installation

This is the path to choose if you haven't heard of Docker yet. If you have experience with this virtualisation software, we'd suggest to install BioCASe from the Docker image (instructions in section Installing from a Docker image).

BioCASe runs on both Windows and Linux machines. Two thoughts to consider for you:

• If you want to use ODBC to connect to your database (for example to an Access database), you should make sure that an ODBC driver is available for the OS of your choice. For an Access database, for example, such a ODBC driver is available only for Windows - so you should go for Windows.
• If you don't wanna use ODBC, since you plan to connect to a wide-spread DB system such as MySQL, Postgres or MS SQL Server, we recommend Linux (Debian).

Installing Apache/IIS and Python

If you’re using a Linux system, you probably don’t need to install either, since Apache and Python are usually preinstalled. Same holds true for MacOS, but you should have a look at one of the articles on the web to find out about the file locations.

Even though the BPS runs with both Apache and Internet Information Server (IIS), we recommend using Apache, which is much easier to configure. However, if you’re already using IIS, you might want to stick with that.

The BPS requires Python 2.5+ to run, it doesn't work with Python 3. On most Linux systems, Python 2.7 will be pre-installed, and this works fine with BioCASe. By the way: You can install several different Python versions on the same machine without any conflicts.

If you’re installing on a Windows Vista (poor you) or Windows 7 machine, we recommend not to install Apache in the default program files folder, since there is some magic spell on that which can get you into trouble when changing Apache’s configuration files. Just choose another path (Apache Software Foundation?) to spare that hassle.

Once you’ve successfully installed Apache and Python, you can proceed to the next step.

Downloading the Provider Software

You can download the BPS either as a g-zipped archive or directly from our Subversion repository. First option is the easiest if you’re not familiar with Subversion; the second option makes it easier for you to update your installation later. So if you’ve never used Subversion before and plan not to keep your installation up-to-date, choose the archive. If you plan to set up a productive installation, which should be kept up-to-date, you should opt for the subversion repository.

Downloading the Archive File

Just download the archive from the Download section of the BioCASe site and unpack the contents to the destination folder.

Downloading from the Subversion Repository

If you’re using Windows, you need to install a Subversion client first (try Tortoise, which comes with a nice user interface). Linux and MacOS usually have Subversion preinstalled.

The URL for the latest stable version is http://ww2.biocase.org/svn/bps2/branches/stable, which we recommend to use. Updating your installation to the latest BPS version is then as easy as just running the Subversion update command. If you want to download a defined version, the URL would be http://ww2.biocase.org/svn/bps2/tags/release_2.6.0.

In order to download the BPS from subversion with the Subversion command line client (preinstalled on Linux/MacOS), just go to the destination and type in

svn co http://ww2.biocase.org/svn/bps2/branches/stable biocase

This will connect to our server with anonymous access and download all files to the folder biocase. In case you’re using Tortoise on Windows, right-click on the destination in the Windows explorer and choose Checkout. Fill in the URL, change the destination folder name into something meaningful and press OK:

For the remainder of this guide, we will assume you’ve installed the BPS into a folder named biocase, which should look like this by now:

Running the Setup Script

The setup script will initiate the configuration files with values you provide and point the script files to your Python installation (you can re-run the setup script in case that location changes). If you want to modify any of settings you made during the setup, you can change the values in the configuration tool later.

In order to run the script, open a terminal window (or “command prompt” in Windows). Change the working directory to the folder you’ve downloaded the BPS to (biocase) and type in:

python setup.py

In case Python is not found, you’ll have to add the full path name to the Python executable. Make sure the Python version given in the fifth line of the output is the one you desire (otherwise add the path to the correct executable):

The questions asked by the setup script do have defaults. If you want to keep them, just press Return.

Webserver domain: This is the domain name of the web server you’re installing BioCASe on, e.g. http://www.myinstitution.org. You can keep the default localhost as long as you’re configuring and testing the installation locally; for production you’ll need to change that into the correct domain name (or IP address) later.

Base URL: This will become the second part of the URL your installation will use. If you keep the default biocase, your installation will be accessible later at www.myinstitution.org/biocase, for example.

After answering these two questions, the script will update your files. At the end of the output you can find the lines you'll need later to create the link between BioCASe and your web server, so do not close the window!

Linking BioCASe and Your Web Server

The public part of the provider software is stored in the www subfolder of your BioCASe installation and must be configured in your web server as a public folder. You should always make this folder public using a virtual directory: This means that you should never install BioCASe under the default root folder of your web server. Doing so can compromise your server security and will allow people to see your configuration files (which include passwords). So since we installed BioCASe in c:\biocase, the folder that must be published with a virtual directory is c:\biocase\www and will be accessible later through http://www.myinstitution.org/biocase.

Apache

If you use Apache, adding the BioCASe folder to your web server environment is as simple as copying the lines printed at the end of the setup script to the end of the Apache configuration file httpd.conf. This can typically be found in the conf folder of your Apache installation. If you’re adding BioCASe to an already productive web server, please ask the server admin before doing any changes!

Save the file and restart Apache for the changes to take effect.

Internet Information Server

If you use Internet Information Server, you need to create a virtual directory for the folder c:\biocase\www using the IIS Server Manager. Grant all rights for this directory (Read, Write, Script Execution, Directory listing). You should also add index.html to the list of default documents (Virtual Directory > Properties > Documents > Default).

In order to associate Python scripts with Python in IIS 5/6, you need to use the Configure button on the virtual directory tab and associate the file extensions .cgi and .py with Python (see screenshot below). In IIS 7, you can open this dialog by choosing Add Script Map. Note the placeholders %s %s after the Python executable!

If you run into problems configuring IIS, you should have a look at the tutorials available on the web, for example

• http://haishibai.blogspot.de/2011/02/setting-up-python-on-iis-7_01.html
• http://support.microsoft.com/kb/276494
• http://www.ecp.cc/pyiis.html

Testing the Link

Once you’re done, you can test your BioCASe Installation by opening a browser and typing in http://localhost/biocase (replace localhost with the domain name of the machine you installed BioCASe on, if you’re not working locally). You should then see the start page of the BPS:

Installing Additional Python Packages/Java

Before you can start configuring your installation, you need to install additional packages, depending on the management system used for the database to be published and the functions of the BPS you intend to use.

On the BPS start page, click on Utilities, then library test in order to navigate to the library test page that shows the status of installed libraries. On a fresh BPS installation, it should look similar to this:

The BioCASe libraries are already included in the archive file you’ve downloaded (or the Subversion repository you checked out from). The 4SuiteXML library is required only for the Local Query Tool – if you don’t plan to use it, you can ignore it. Otherwise click on the Download link, find the installer appropriate for your operating system and install it.

For each DBMS you plan to use with BioCASe (i.e. you have a database you want to publish with BioCASe), you’ll have to install the corresponding package. So if your collection is stored in a MySQL database, for example, click on the download link for the MySQL module, find the correct installer for your Python version and operating system and install. Once the installation is done, after reloading the libraries test page in the browser, the according list entry should turn from an orange ‘not installed’ into a green version number. Redo this process for all DBMS you want to connect to.

The Graphviz library listed under optional external binaries is used by the BPS to create a graph of your database’s data model in the table setup (you will learn in the Table Setup about this). If the data model is very simple (i.e., not more than 3 or 4 tables), you probably can spare the effort of installing Graphviz. Otherwise we recommend installing it: Simply click on the Download link, find the correct installer, and… you know the story.

If you want to create DarwinCore Archives for your web services, you also need to install a Java Runtime Environment (JRE). If it is installed on the machine, but the version is not shown as in the screenshot above, please specify the full path to the Java executable.

Changing the Default Password

The configuration tool is a browser interface that allows you to configure almost every aspect of the BPS. As a last step of the setup, you should change the password.

Go back to the Start page of the BPS (by clicking Start at the top of the page, or by retyping http://localhost/biocase if the server is running on your computer), choose Config Tool, then System Administration. You will then be prompted for a password. Type in the default ACDC, then click Submit.

The top of the configuration page you’ll be directed to should look similar to this:

In the first two lines, you’ll see the values you entered during the setup script (in this case, the defaults localhost and biocase). In the fourth line, enter a new password. Please be careful when typing (if you forget the password some day, you can reset it by directly editing the configuration file). Press update config to save the new password to the configuration file.

In case you’ve installed Graphviz, you need to tell the BPS the location of the binaries, since it is not a Python package that will be registered automatically. In order to do so, locate the Graphviz installation on your local disk and enter the path to the binary executable into the text box labelled Graphviz dot binary. On Linux machines it might look similar to the default (/usr/local/bin/dot), on Windows machines it will be probably something like C:\Program Files\Graphviz2.26.3\bin\dot.exe. Press update config to save the path.

Checking Your Installation

Before you proceed to the configuration, you should make sure everything is installed correctly:

1. Typing in http://localhost/biocase (or the appropriate values of your installation) takes you to the entry page of the provider software (as shown in the section Linking BioCASe and Your Web Server).
2. The libraries test page (Utilities > library test) shows you’ve installed the packages for you DBMS, 4SuiteXML (if you want to use the Local Query Tool), Java (if you want to create DarwinCore Archives) and the Graphviz Dot (if you decided so).
3. Status of writeable directories shows a green writeable for all four directories. If not, the path to problematic file will be given – please grant write access to Python.

Let’s assume you want to use BioCASe in conjunction with a MySQL and an Access database (which will be connected to through ODBC) and you don’t care for the Query Tool, the libs page should look like this:

Installing BioCASe from a Docker image

Good choice! Installing BioCASe from a Docker image is much easer than installing the installed components step-by-step. In addition, it's easier to update an exisiting installation. If you don't know yet what Docker is, you should read the Get Started Guide first.

Important note: BioCASe requires Docker version 17 or later. If you already have Docker installed, run docker --version in a terminal and make sure the version number is 17+.

For installing BioCASe from the Docker image, please follow these steps:

1. Install Docker Community Edition (Docker CE). For detailed instructions, see About Docker CE and choose the tutorial for your platform. To make sure Docker is properly installed, run docker --version in a terminal and make sure the version number is 17+.
2. Download the Makefile that contains the commands for installing and updating BioCASe. Use "Save as..." to store it to your home folder on the server machine.
3. Open a terminal window and change the work directory to the location you've just saved the Makefile to. Then type in make install and press enter. This should download the latest BioCASe image, create a BioCASe container and run it.

Per default, Docker will use port 80 for BioCASe. If this port is already used by another application on your server, you can instruct Docker to use another port. For using port 8181, for example, type in make install PORT=8181 instead:

Voilà, that's it! To check your BioCASe installation, use your Browser to go to http://localhost/biocase.

You can also use the Makefile for stopping and starting the BioCASe container - just type make stop and make start. For removing the container, use make remove, for updating your BioCASe installation make update.

Important note: The configuration and the log files of your BioCASe installation, as well as any XML and DwC archives created, will be store in Docker hosted volumes. That means they are stored outside of the BioCASe container and will be preserved, even when the container is removed (actually, that's what happens if you update your installation). Docker hosted volumes are stored in the volumes folder of your docker installation, e.g. /var/lib/docker/volumes. If you want to backup the configuration of your BioCASe installation, just backup the folder /var/lib/docker/volumes/bps_config. To learn more about docker hosted volumes, please refer to the Docker guide.

Updating an existing BioCASe Installation

Updating a regular BioCASe installation

Important Note: If you have a running BioCASe installation, you shouldn’t touch it until you’ve successfully installed a new version. So keep the old installation instead of replacing it!

Updating from version 2.5 or later

1. Rename the folder of the old installation to something meaningful, for example biocase_old, and memorise its old name. By doing this, you can always revert to this working version.
2. Download the new version as described above into a directory with the name you just memorised.
3. Change directory to the new installation and run setup script. When asked whether to import the configuration from an old installation, answer yes. The setup script will now import the configuration of the old installation, including the data sources.
4. Done! Try out your new installation to make sure it is working.

Updating from older versions < 2.5

1. Rename the folder of the old installation to something meaningful, for example biocase_old, and memorise its old name. By doing this, you can always revert to this working version; moreover, you will need the configuration files later.
2. Download the new version as described above into a directory with the name you just memorised.
3. Run the setup script. When asked whether to import the configuration from an old installation, just press Return (defaults to no). Make sure to provide the the same base URL that was used by the old installation (for example /biocase).
4. Change the default password of the new installation to the one you used in the old installation.
5. Open the file config/config.ini of your old installation in a text editor. Open the config tool of the new installation and navigate to the System Administration page. Compare the settings in the section Server configuration with the values you can find in the old configuration file and change them, if necessary (leave values unchanged if you don't find them in the old file). Press Update config.
6. Last, copy the configuration of the BioCASe web services: Open the folder config/datasources of your old installation and copy all subfolders to config/datasources of your new installation.
7. Done! Try out your new installation to make sure it is working.