Ensembl Home
More ▼
Search »
In this section
On this page

Configuring an Ensembl Website

This section explains the configuration changes you have to make so that Ensembl will run on your local set-up.

Setting up the "Mirror Plugin"

In the main ensembl-webcode/conf directory you will find a file called Plugins.pm-dist. Copy this file and name it Plugins.pm (i.e. without the -dist extension). This file sets up any plugins required by the website, including the mirror plugin mentioned above. 

$SiteDefs::ENSEMBL_PLUGINS = [
  'EnsEMBL::Mirror'     => $SiteDefs::ENSEMBL_SERVERROOT.'/public-plugins/mirror',
  'EnsEMBL::Genoverse'  => $SiteDefs::ENSEMBL_SERVERROOT.'/public-plugins/genoverse',
# 'EnsEMBL::Solr'       => $SiteDefs::ENSEMBL_SERVERROOT.'/public-plugins/solr',
# 'EnsEMBL::Users'      => $SiteDefs::ENSEMBL_SERVERROOT.'/public-plugins/users',
  'EnsEMBL::Ensembl'    => $SiteDefs::ENSEMBL_SERVERROOT.'/public-plugins/ensembl'
  'EnsEMBL::Docs'       => $SiteDefs::ENSEMBL_SERVERROOT.'/public-plugins/docs'
];

Background: configuration

Plugins

The default configuration files can all be found in the "conf" subdirectory of the ensembl-webcode repo. The site-wide configuration (Apache config, global settings) is stored in ensembl-webcode/conf/SiteDefs.pm.

Elsewhere in the documentation you will read about how to extend Ensembl by writing your own plugins. A by product of this extensibility is that you can also use plugins to simply configuration of your server. For example, in your checked-out copy of Ensembl there is a public-plugins/mirror directory. The mirror/conf directory contains DEFAULTS.ini and SiteDefs.pm files which can be used to configure your copy of Ensembl.

Configuring the available species

If you wish to add to or remove from the full list of species on the main Ensembl website, please see the documentation on extending Ensembl.

As you can see, the default mirror setup uses up to six plugins:

    home pages and public documentation
  • public-plugins/mirror, which contains only the files needed to configure your mirror
  • public-plugins/genoverse, the scrolling browser used on Region in Detail - this can be omitted if your users are dependent on very old browsers with poor Javascript support
  • public-plugins/users, an optional plugin for user accounts
  • public-plugins/solr, an optional plugin for our search engine - see below
  • public-plugins/ensembl, which contains all the species configuration files and documentation specific to Ensembl vertebrate species (e.g. genebuild, compara statistics)
  • public-plugins/docs, which contains technical documentation for Ensembl software (including this installation guide)

Note that the array of plugins is in order of precedence, so that in the default setup, the mirror plugin overrides the base Ensembl one. DO NOT edit the files in public-plugins/ensembl, as your changes may be overwritten when you update to the next release.

Now go into the public-plugins/mirror/conf directory and make the changes listed below to SiteDefs.pm and ini_files/DEFAULTS.ini:

public-plugins/mirror/conf/SiteDefs.pm

First copy SiteDefs.pm-dist to SiteDefs.pm in this directory. If you open this file in a text editor, such as vi, you will see it is a Perl module with a single method "update_conf" which contains the changes needed to configure your copy of the website.

Below are the variables you will need to change to match your installation. If you wish, you can change any variables that are defined in the main SiteDefs.pm file.

Note: You should only change the values, that is the parts between single quotes.

General configuration

$SiteDefs::ENSEMBL_SERVERROOT sets the filesystem location of the web server root directory. By default, this is determined dynamically based on the location of the SiteDefs.pm file. You can, however, hard-code this value if you wish. For example, if you installed the Ensembl site in /usr/local/ensembl, then you could change this line of SiteDefs to read:

  $SiteDefs::ENSEMBL_SERVERROOT = '/usr/local/ensembl';

Configuration of the Apache web server

Change $SiteDefs::ENSEMBL_SERVERNAME to the web name of the server - e.g. "www.yoursite.org". This value is dynamically set to the server hostname by default.

Note that you will need to start Apache on an unprivileged port (i.e. not 80) with a non-root user, as for internal maintenance reasons we have removed the option to set the Apache user manually.

Mail configuration - error messages

If you want errors to be automatically emailed to you, change $SiteDefs::ENSEMBL_MAIL_ERRORS to the value 1, and change $SiteDefs::ENSEMBL_ERRORS_TO to your email address. If you don't want errors mailed, set $SiteDefs::ENSEMBL_MAIL_ERRORS to 0.

Temporary Files

There are three temporary file locations that can optionally be configured:

  $SiteDefs::ENSEMBL_TMP_DIR       General storage for temporary files
  $SiteDefs::ENSEMBL_TMP_DIR_IMG   Storage for image files
  $SiteDefs::ENSEMBL_TMP_DIR_BLAST Storage for blast files

The first of these will default to $ENSEMBL_SERVERROOT/tmp, and the other locations will default to subdirectories of this location, but you can specify your own filesystem paths if you wish.

public-plugins/mirror/conf/ini-files/DEFAULTS.ini
and public-plugins/mirror/conf/ini-files/[Species_name].ini

Again the first thing to do is make a copy of the DEFAULTS.ini-dist file as DEFAULTS.ini, then you will need to go in and edit the appropriate lines of the DEFAULTS.ini.

The format of the species-specific .ini files are similar to a standard windows ini file, i.e. split into sections identified by a header in square brackets, which contain key = value entries. When the Apache server is started, these files are parsed and stored in a file called config.packed in the conf directory. This config.packed file can be regenerated when the server is restarted.

Database configuration

In the [general] section, change the values of DATABASE_DBUSER and DATABASE_DBPASS to the username and password you want MySQL to be accessed by. Set DATABASE_HOST and ENSEMBL_HOST_PORT to be the database server and port that MySQL is running on.

These are default settings - you can override them by adding a section for a particular database. For example, adding a section like the following into the mirror plugin would override the defaults in public-plugin for the ENSEMBL_WEBSITE database:

[DATABASE_WEBSITE]
USER=mysqluser2
PASS=helppass
HOST=mysqlserver2
PORT=4444

Fonts

Ensembl uses TrueType fonts in its images, so these need to be configured in the '[ENSEMBL_STYLE]' section of the DEFAULTS.ini file. 

[ENSEMBL_STYLE]
GRAPHIC_FONT         = arial                           ; Arial file is arial.ttf
GRAPHIC_FONT_FIXED   = cour                            ; Courier file is cour.ttf
GRAPHIC_TTF_PATH     = /usr/local/share/fonts/ttfonts/ ; remember the trailing slash
GRAPHIC_FONTSIZE     = 8                               ; Default font-size for graphic text...

You will likely need to change the path to where your local copy of these files is stored. Please note that Mac TTF files are a slightly different format and do not reliably work.

public-plugins/mirror/conf/ini-files/MULTI.ini

Create this file to configure the multi species databases. Configure the [general] section for connection to the MySQL server, as for the species-specific ini files. In the [databases] section, change the values of DATABASE_COMPARA entry to match the name of the ensembl_compara database that you created.

In addition, if you chose to install a local GO database you can configure it here by adding an entry:

DATABASE_GO = your_go_database_name

to the [databases] section along with DATABASE_COMPARA.

Session database

Change the values of the following to have the details for your web_user database

[ENSEMBL_SESSION]
HOST = sessiondb_host
USER = sessiondb_user
PASS = sessiondb_password

Remember this database needs a user with update/insert/delete privileges. Additionally if you wish to change the encryption keys used to "protect" the cookies, $SiteDefs::ENSEMBL_ENCRYPT_0 should be a six digit hex-number and $SiteDefs::ENSEMBL_ENCRYPT_1, _2 and _3 should each contain two alphanumeric characters. Unless you are particularly concerned about people changing cookies, the default values will probably do.

BLAST

BLAST is not installed by default. You have to configure blast for a local installation. See documentation describing how to configure BLAST.

All relevant fasta files are on https://ftp.ensembl.org/pub/grch37.

Note on Ensembl Web Site Search

By default, local installations of Ensembl use a simple search that just does SQL searches against the database. This method is rather slow and crude, however. Also, it does not do cross species queries (too time consuming for MySQL queries).

The Ensembl web site uses the open-source Java-based Solr search engine. If you wish to use this search engine, you will need to download the Solr software and set up a Tomcat server, as well as installing our search indices. Full instructions are provided on our FTP site at https://ftp.ensembl.org/pub/grch37/current_solr_search/.

Site Preparation

cd into your server root and run the following commands:

  ./ensembl-webcode/ctrl-scripts/init

This will create all the temporary directories required by the Ensembl webcode.

Your Ensembl site should now be ready to start up.

DISCLAIMER

Please note that the suggested set-up for Apache, mod_perl, MySQL and all Ensembl modules is not intended to provide high-level security. We strongly recommend that you get your systems administrator to audit any system that you provide to others. In particular, note that the perl.startup file in the conf directory may be run as root, so be careful about permissions on this file.

We are not responsible for any damage or loss of data resulting or arising from running the Ensembl website on your own machines.

Next: Running the Site →