Deploy oPOSSUM3

· 3 min read · Tutorials

Deploy oPOSSUM3

Deploy oPOSSUM3

Deploy oPOSSUM3: Transcription Factor Analysis

TL;DR: oPOSSUM3 is a web-based system for analyzing transcription factor binding sites (TFBS) in gene lists. It is legacy software (Perl/CGI) and difficult to install. This guide provides a Docker-based deployment strategy and manual installation steps for preservation.

What is oPOSSUM3?

oPOSSUM3 detects over-represented transcription factor binding sites (TFBS) in a set of co-expressed genes compared to a background set. It uses the JASPAR database of TFBS profiles.

Use cases:

  • ChIP-seq peak analysis
  • Promoter analysis of differentially expressed genes (bulk RNA-seq)
  • Identifying master regulators from gene lists

Modern Alternative: For single-cell data or R-based workflows, use RCisTarget (the engine behind SCENIC). Use oPOSSUM3 if you specifically need its unique scoring methods or web interface.

Method 1: Docker Deployment (Recommended)

Installing oPOSSUM3 manually involves configuring Apache, MySQL, Perl, and BioPerl. Using Docker avoids this dependency hell.

1. Create Dockerfile

Save this as Dockerfile:

FROM ubuntu:20.04

ENV DEBIAN_FRONTEND=noninteractive

# Install dependencies
RUN apt-get update && apt-get install -y \
    apache2 \
    mysql-server \
    mysql-client \
    build-essential \
    libmysqlclient-dev \
    cpanminus \
    bioperl \
    git \
    wget \
    unzip \
    && rm -rf /var/lib/apt/lists/*

# Install Perl modules
RUN cpanm --notest \
    CGI \
    CGI::Application \
    Data::Dumper \
    DBI \
    DBD::mysql \
    File::Temp \
    Log::Log4perl \
    Statistics::Distributions \
    Statistics::R \
    Template

# Install TFBS (Legacy)
WORKDIR /opt
RUN wget http://tfbs.genereg.net/TFBS-0.7.0.tar.gz && \
    tar -xzf TFBS-0.7.0.tar.gz && \
    cd TFBS-0.7.0 && \
    perl Makefile.PL && \
    make && \
    make install

# Configure Apache (CGI support)
RUN a2enmod cgi
COPY apache-opossum.conf /etc/apache2/sites-available/000-default.conf

# Expose ports
EXPOSE 80 3306

CMD service mysql start && service apache2 start && tail -f /var/log/apache2/error.log

2. Build and Run

# Build image
docker build -t opossum3 .

# Run container
docker run -d -p 8080:80 -p 3306:3306 --name opossum opossum3

Visit http://localhost:8080/opossum to access your local instance.

Method 2: Manual Installation (The Hard Way)

If you must install it on bare metal (e.g., an academic server), follow these steps carefully.

1. Prerequisites (Perl & BioPerl)

# Install BioPerl
cpanm Bio::Perl

# Install TFBS
wget http://tfbs.genereg.net/TFBS-0.7.0.tar.gz
tar xvfz TFBS-0.7.0.tar.gz
cd TFBS-0.7.0
perl Makefile.PL
make
make install

Note: You must manually install JASPAR5.pm from the TFBS SVN repository if it's missing from the tarball.

2. Required Perl Modules

Install via CPAN:

cpanm CGI CGI::Application DBI DBD::mysql Log::Log4perl Statistics::R Template

3. Database Setup (MySQL)

oPOSSUM relies on a local MySQL database populated with JASPAR data.

A. Install MySQL

sudo apt install mysql-server

B. Download Databases
You need the species-specific databases (Human, Mouse, etc.) and the JASPAR DB.

  • JASPAR: http://cisreg.ca/pub/JASPAR/
  • oPOSSUM DBs: Hosted at opossum.cmmt.ubc.ca

C. Load Data

# Unzip and load
gunzip -c oPOSSUM3_human.sql.gz | mysql -u root -p oPOSSUM3_human

D. Create Database User

CREATE USER 'opossum_r'@'localhost' IDENTIFIED BY 'password';
GRANT SELECT ON oPOSSUM3_human.* TO 'opossum_r'@'localhost';
GRANT SELECT ON JASPAR_2010.* TO 'opossum_r'@'localhost';
FLUSH PRIVILEGES;

4. Web Server Configuration

  1. Symlink CGI Scripts:
    Link the oPOSSUM cgi-bin directory to your Apache cgi-bin.

    ln -s /apps/oPOSSUM3/cgi-bin /usr/lib/cgi-bin/oPOSSUM3

  2. Configure Permissions:
    Ensure the web user (www-data) can write to temp directories.

    mkdir -p htdocs/tmp htdocs/results
chown -R www-data:www-data htdocs/tmp htdocs/results

  3. Edit Config:
    Modify lib/OPOSSUM/Web/Opt/BaseOpt.pm to match your paths (MySQL user, temp dir, URL).

Troubleshooting

"Can't locate Bio/Perl.pm"

Cause: BioPerl not in @INC.
Fix: Ensure PERL5LIB environment variable includes your BioPerl installation path.

"DBD::mysql installation failed"

Cause: Missing libmysqlclient-dev.
Fix: sudo apt install libmysqlclient-dev before installing the Perl module.

"Analysis times out"

Cause: TFBS scanning is slow.
Fix: Increase Apache Timeout setting in httpd.conf to 600 or more.

Resources

See also:

Originally posted on WeChat Official Account: bioinfo_studyroom

Server Setup TF Activity