Deployment Manual

CLC Workbenches
Manual for
CLC Workbenches: deployment and technical information, version 1.6
Windows, Mac OS X and Linux

August 30, 2013

This software is for research purposes only.

CLC bio
Silkeborgvej 2
Prismet
DK-8000 Aarhus C
Denmark
Contents

1 Introduction 6
1.1 Deployment strategies . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 6
1.2 System requirements . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 7

2 Java Web Start 10

2.1 Launching a Workbench through Java Web Start . . . . . . . . . . . . . . . . . . . 10
2.2 System requirements for the Java Web Start Administration Tool . . . . . . . . . . 10
2.3 Installation of the Java Web Start Administration Tool . . . . . . . . . . . . . . . . 11
2.3.1 User name and password . . . . . . . . . . . . . . . . . . . . . . . . . . . 11
2.3.2 User interface overview . . . . . . . . . . . . . . . . . . . . . . . . . . . . 11
2.4 Installing and managing distributions . . . . . . . . . . . . . . . . . . . . . . . . . 11
2.5 Creating and managing profiles . . . . . . . . . . . . . . . . . . . . . . . . . . . . 12
2.5.1 Creating a profile . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 13
2.5.2 Plug-ins . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 14
2.5.3 Profile settings . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 14
Property files . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 15
Codon frequencies . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 15
User preferences and view preferences . . . . . . . . . . . . . . . . . . . 16
Restriction enzyme database . . . . . . . . . . . . . . . . . . . . . . . . . 16
2.6 Custom handling of bug submission . . . . . . . . . . . . . . . . . . . . . . . . . 16

3 Installation without Java Web Start 18

3.1 Available installers . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 18
3.1.1 Java . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 18
Java on Mac . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 18

3
CONTENTS 4

3.1.2 Overview of available installers . . . . . . . . . . . . . . . . . . . . . . . . 19

3.2 What does it do? . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 19
3.2.1 Extracting and copying files to the installation directory . . . . . . . . . . . 19
3.2.2 Setting the amount of memory available . . . . . . . . . . . . . . . . . . . 19
3.2.3 Shortcuts and file associations . . . . . . . . . . . . . . . . . . . . . . . . 19
3.3 Silent installation . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 20

4 License 21
4.1 License server set-up on clients . . . . . . . . . . . . . . . . . . . . . . . . . . . 21

5 Plug-ins and resources 23

6 Workflows 24

7 Connecting to a CLC Server 25

8 Security policies 26

9 Storing and backing up data 28

9.1 Storing data . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 28
9.1.1 Data structure . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 28
9.1.2 Changing the default location . . . . . . . . . . . . . . . . . . . . . . . . . 29
9.2 Back-up of data . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 30
9.3 Special configurations for large amounts of data . . . . . . . . . . . . . . . . . . 30
9.3.1 Temporary data . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 30
9.3.2 Disk space requirements . . . . . . . . . . . . . . . . . . . . . . . . . . . 31

10 System resources 32
10.1 Setting the amount of memory available for the JVM . . . . . . . . . . . . . . . . 32
10.2 Setting the number of cores to use . . . . . . . . . . . . . . . . . . . . . . . . . . 33

11 Overview - where do we put things? 34

11.1 Computer-level information . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 34
11.2 Property files overview . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 34
11.3 User-level information . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 35
CONTENTS 5

A Appendix 36
A.1 Java Web Start troubleshooting . . . . . . . . . . . . . . . . . . . . . . . . . . . . 36
A.1.1 Cannot start Workbench when offline . . . . . . . . . . . . . . . . . . . . . 36

Index 36
Chapter 1

Introduction

If you are in charge of installing and maintaining CLC Workbenches in your organization, you
probably have a lot of questions about installers, licenses, and where do we put files for this and
that.
This manual is written to answer these questions. It is primarily aimed towards client installations
(i.e. the CLC Workbenches). For installing the CLC Bioinformatics Database and CLC Server,
please refer to the installation chapter in the respective user manuals (see http://www.
clcbio.com/usermanuals).
At the moment, the CLC Workbenches are:

• CLC Main Workbench

• CLC Genomics Workbench

In addition, there is the CLC Sequence Viewer which is very similar to the other Workbenches
except when it comes to licensing (it is free) and plug-ins (some plug-ins cannot be installed in
the CLC Sequence Viewer).
In the first part of this manual, we take a closer look at the deployment strategies. Then we
go into details of the license system, followed by an explanation of the concept of plug-ins and
workflows. Finally there is an overview chapter which tells you where to find all the different
files in a client installation. This is useful when deploying the Workbench but also for back-up
purposes.
We will not go into details of Linux installations, but if you need these details, please contact us.
Questions, comments and feedback on this manual are very welcome at [email protected].

1.1 Deployment strategies

Deployment strategies should be developed so that they fit your existing IT set-up. There are two
main ways of deploying CLC Workbenches.
The first strategy is to use Java Web Start which is the method that has the best direct support
from CLC bio. In short, Java Web Start is a system where users initially start the Workbench from

6
CHAPTER 1. INTRODUCTION 7

a central configuration, and whenever changes to this configuration is made, the user versions
are automatically updated. The Java Web Start support is described in section 2.
The second strategy requires more work on the administrator side to make sure that local
installations are updated, as there are no special tools provided by CLC bio. However, the
Workbench is very self-contained and simple to configure, so this solution has proven to work in
many cases. Note that this is a brief summary of the steps to take, and that the rest of this
manual is devoted to more detailed information.

1. On a single computer with the same OS as the target computers, complete a full installation
including:

• Running the installer (read more about what installers in section 3)

• Set up license server connection 1
• Install plug-ins and resources
• Configure security policies, path for temporary data and default location (see more
information in this manual)
• Specify proxy server information if needed

2. Run the installer in silent mode (-q) on all the target computers

3. Copy the following files from the installation in 1) to the target computers

• All files from the settings folder in the installation directory

• plugins and resource folder from the installation directory

We recommend you tailor this strategy to your own organization - this is just an example of how
it can be done.
Creating a GHOST image or similar to copy to all the target computers is also a possibility, but
there are a few routines performed by the installer that need to be taken into account, especially
allocating memory (see section 10.1) and the creation of shortcuts and file associations.

1.2 System requirements

The system requirements of the CLC workbenches except the CLC Genomics Workbench are
these:

• Windows XP, Windows Vista, Windows 7, Windows 8, Windows Server 2003 or Windows
Server 2008

• Mac OS X 10.6 or later. However, Mac OS X 10.5.8 is supported on 64-bit Intel systems.

• Linux: Red Hat 5.0 or later. SUSE 10.2 or later. Fedora 6 or later.

• 32 or 64 bit

• 256 MB RAM required

1
If you do not use a license server, you will have to activate licenses on each computer
CHAPTER 1. INTRODUCTION 8

• 512 MB RAM recommended

• 1024 x 768 display recommended

The requirements for the CLC Genomics Workbench are:

• Windows XP, Windows Vista, Windows 7, Windows 8, Windows Server 2003 or Windows
Server 2008

• Mac OS X 10.6 or later. However, Mac OS X 10.5.8 is supported on 64-bit Intel systems.

• Linux: Red Hat 5.0 or later. SUSE 10.2 or later. Fedora 6 or later.

• 1024 x 768 display recommended

• Intel or AMD CPU required

• Special requirements for the 3D Molecule Viewer

System requirements
∗ A graphics card capable of supporting OpenGL 2.0.
∗ Updated graphics drivers. Please make sure the latest driver for the graphics card
is installed.
System Recommendations
∗ A discrete graphics card from either Nvidia or AMD/ATI. Modern integrated graphics
cards (such as the Intel HD Graphics series) may also be used, but these are
usually slower than the discrete cards.
∗ A 64-bit workbench version is recommended for working with large complexes.

• Special requirements for read mapping. The numbers below give minimum and rec-
ommended memory for systems running mapping and analysis tasks. The require-
ments suggested are based on the genome size. Systems with less memory than
specified below will benefit from installing the legacy read mapper plug-in (see http:
//www.clcbio.com/plugins). This is slower than the standard mapper but adjusts to
the amount of memory available.

E. coli K12 ( 4.6 megabases)

∗ Minimum: 2Gb RAM
∗ Recommended: 4Gb RAM
C. elegans ( 100 megabases) and Arabidopsis thaliana ( 120 megabases)
∗ Minimum: 4Gb RAM
∗ Recommended: 8Gb RAM
Zebrafish ( 1.5 gigabases)
∗ Minimum: 8Gb RAM
∗ Recommended: 16Gb RAM
Human ( 3.2 gigabases) and Mouse ( 2.7 gigabases)
∗ Minimum: 24Gb RAM
∗ Recommended: 48Gb RAM
CHAPTER 1. INTRODUCTION 9

• Special requirements for de novo assembly. De novo assembly may need more memory
than stated above - this depends both on the number of reads, error profile and the
complexity and size of the genome. See http://www.clcbio.com/white-paper for
examples of the memory usage of various data sets.

• 64 bit computer and operating system required to use more than 2GB RAM
Chapter 2

Java Web Start

The Java Web Start system is an easy way to maintain a central configuration of a Workbench
that is deployed to all end-users. CLC bio provides a tool with a web interface for systems
administrators to manage the Workbench configurations. The explanation of the various aspects
of Java Web Start deployment will be coupled with the explanation of how to use this tool in the
rest of this chapter.
Please let your contact person at CLC bio or [email protected] know that you are interested
in using Java Web Start for deploying Workbenches, and you will get access to downloading the
necessary resources through MyCLC: http://my.clcbio.com/.

2.1 Launching a Workbench through Java Web Start

When a user wants to start a Workbench deployed through Java Web Start, the user launches a
so-called jnlp file instead of launching an application installed on the user computer. The jnlp
file is typically accessed through a link on an internal web page or in an email. The Java runtime
on the user computer is used to launch the jnlp file, so Java has to be installed. The jnlp file
corresponds to a Workbench profile, that the systems administrator has set up using the Java
Web Start Administration Tool (elaborated below), and this Workbench profile is then launched on
the user computer.
When the Workbench is launched, a shortcut is created on the user's desktop,1 allowing quick
access to re-launch the workbench without finding the downloaded jnlp file or the link to download
it again. When the Workbench is re-launched, it will check if the profile has been updated,
and any changes will reflect immediately on the user side. If the server running the Java Web
Start Administration Tool cannot be reached from the user computer, a local cache will allow the
Workbench to still be launched, but any changes to the profile in the Java Web Start Administration
Tool will only take effect when the Workbench is launched while the server can be reached.2

2.2 System requirements for the Java Web Start Administration Tool
• Windows XP, Windows Vista, or Windows 7, Windows Server 2003 or Windows Server 2008
1
The standard shortcut will have a Java-style icon. To create a proper CLC Workbench icon, go to Help and Create
Shortcut when the Workbench is started.
2
Please refer to the appendix section A.1.1 if there are problems running the Workbench while off line.

10
CHAPTER 2. JAVA WEB START 11

• Mac OS X 10.6 or later. However, Mac OS X 10.5.8 is supported on 64-bit Intel systems.

• Linux: Red Hat or SUSE

• 32 or 64-bit

• 256 MB RAM required

2.3 Installation of the Java Web Start Administration Tool

Download the installer for the Java Web Start Administration Tool at http://my.clcbio.com/
and install the tool on your local server. This server must be accessible from Workbench client
computers in order for these to launch the Workbench initially and receive updates. Although
they will be able work off-line as explained in section 2.1.
Once the installation has been completed, you can access the Java Web Start Administration Tool
web interface by entering the host name on port 8080. For example localhost:8080 if your
browser is on the computer where the Java Web Start Administration Tool is installed.

2.3.1 User name and password

The default user name and password is:

User name admin

Password admin

The login mechanism of the tool is very simple. The user name and password are stored in a file
called tomcat-users.xml in the conf folder of the installation directory. Find the following
line to change this:

<user username="admin" password="admin" roles="webstartadmin"/>

We recommend that these are changed after installation.

2.3.2 User interface overview

Once logged in, the user interface presents you with three sections as shown in figure 2.1
The three sections are explained in detail in the following sections of this chapter.

2.4 Installing and managing distributions

The first step in using the Java Web Start Administration Tool is to upload a Workbench distribution
of the version of the Workbench you wish to deploy. The Workbench distribution comes as a .cwd
(for CLC Workbench Distribution) file which is downloaded through http://my.clcbio.com/
(you need to be granted access first, see section 2). Please note that you may see old
distributions named .war instead, and they are equally capable of being used with the Java Web
Start Administration Tool.
CHAPTER 2. JAVA WEB START 12

Figure 2.1: An overview of the web interface of the Java Web Start Administration Tool.

Once the .cwd file is downloaded, the file has to be uploaded through the administrator web
interface:
Manage Workbench Distributions | Manual install workbench distribution | Select
the .cwd/war file | Upload
Once the file is uploaded, switch to the Installed workbench distributions tab to see an overview
of the different Workbench versions installed (see figure 2.2.

Figure 2.2: One version of CLC Genomics Workbench and one version of CLC Main Workbench
are installed.

To delete a distribution, click on it and select Delete distribution.

2.5 Creating and managing profiles

Profiles is the term used for the actual Workbench configuration that an end-user launches. The
profile is based on a specific distribution with a number of setting files, plug-ins and configurations
on top.
For each profile, a JNLP file is created. The JNLP file is the file that users should access to
launch the Workbench. As an administrator, you can provide a link to the JNLP file either through
sending an email to the relevant users, or it can be put on an internal web page. The idea is that
when changes happen to the profile (e.g. the distribution behind it is updated, a new plug-in is
made available etc), the users do not need to worry - this is automatically taken care of as long
as it is based on the same profile.
CHAPTER 2. JAVA WEB START 13

2.5.1 Creating a profile

To create a new profile:
Manage Profiles | Create profile
The following information can be entered for a profile (see figure 2.3).

Figure 2.3: Creating a new profile.

Clone existing profile This can be used if the new profile should be based on an existing profile.

Profile name This is the human-readable name of the profile.

Profile key This will be used to construct the link to the JNLP file that users need to launch the
Workbench.

Max memory This is the memory setting for starting the Workbench (learn more in section 10.1).

JVM parameters This is an advanced feature that should only be used if special instructions are
received from CLC bio Support or someone with expertise in Java Virtual Machines.

Distribution A list of distributions available (read more in section 2.4).

Click Save to save the profile.

The profile is now shown in the Profiles tab as shown in figure figure 2.4.

Figure 2.4: An overview of all profiles.

CHAPTER 2. JAVA WEB START 14

The link to the JNLP file for each profile can be found in this list. In addition, by clicking the
profile, it can be edited, deleted or exported. An exported profile can be imported again using the
tab next to Create Profile.

2.5.2 Plug-ins
Each profile can have a number of plug-ins pre-installed. End-users can also install plug-ins
unless this has been disallowed in the policy properties file (see chapter 8).
The plug-ins are managed for each profile under the Plug-ins section in the menu on the left hand
side. An overview of all plug-ins that are currently installed is shown, as well as the option to
download or manually install plug-ins.
When switching to Download plug-ins, a list of all plug-ins distributed by CLC bio is shown (see
figure 2.5)

Figure 2.5: A list of all plug-ins distributed by CLC bio.

Click a plug-in to read more. Use the checkboxes to select multiple plug-ins for convenient
download and installation. For plug-ins distributed by CLC bio that you install, when a new release
of the plug-in is made available, it will show up in the list of installed plug-ins with an option to
update it.

2.5.3 Profile settings

The Settings tab of a profile (see figure 2.6) allows you to customize the Workbench in a number
of ways.
There are two kinds of settings: property files and settings folders. The property files can be
added and the contents manipulated directly in the web interface, or they can be uploaded by
using the browse and upload buttons at the bottom. The settings folders are used to contain
customized files that are uploaded.
The two kinds of settings are elaborated below.
CHAPTER 2. JAVA WEB START 15

Figure 2.6: Settings to customize the Workbench profile.

Property files
The web interface allows you to manipulate property files directly. When a new profile is created,
two property files are created per default (license information and policies), but others can be
created as well. For a an overview of all the properties that can be managed in this way, look at
section 11.2.
The property files can be edited directly in the web interface as shown for the license property
file in figure 2.6, or they can be uploaded.

Codon frequencies
In the Workbench installation folder under res, there is a folder named codonfreq. This folder
contains all the codon frequency tables organized into subfolders in a hierarchy. These are
available in the Workbench user interface when performing reverse translation.
If additional frequency tables are needed, they can be added to the profile by selecting the Codon
frequencies and clicking browse and Upload to upload a new codon frequency file.
The format needs to follow the format of the cftbl files located in the Workbench installation
folder, so please use one of these as template.
Note! Please be aware that this process needs to be handled carefully, since there are no
validation of the format of the files provided.
CHAPTER 2. JAVA WEB START 16

User preferences and view preferences

In the Workbench, it is possible to export two kinds of preferences. This is best explained in
the Workbench user manual at http://clcsupport.com/clcgenomicsworkbench/602/
index.php?manual=Export_import_preferences.html.
These preferences can be used as the default preferences for a Workbench profile by uploading
them to the User preferences and User view settings folders, respectively.

Restriction enzyme database

The Workbench uses enzymes from the REBASE restriction enzyme database at http://
rebase.neb.com. If you wish to add enzymes to this list, you can do this by using the
procedure described here.
Note! Please be aware that this process needs to be handled carefully, as there are no
validation checks for the new enzymes that are added.
First, download the following file: http://www.clcbio.com/wbsettings/link_emboss_
e_custom.
Open the file in a text editor. The top of the file contains information about the format, and at the
bottom there are two example enzymes that you should replace with your own.
Please note that the CLC Workbenches only support the addition of 2-cutter enzymes. Further
details about how to format your entries accordingly are given within the file mentioned above.
After adding the above file, or making changes to it, upload the file to the Restriction enzyme
database folder in the Settings section.

2.6 Custom handling of bug submission

If an error occurs in the Workbench, or if the user goes to Contact Support in the Help menu,
a bug submission is sent to [email protected]. If you wish bug submissions to be directed
to your internal support team, this can be configured by first creating a property file named
bugsubmission.properties for the Workbench profile (see section 2.5.3).
Next, set up how the bug submissions should be handled in the Manage Bug Submission section
of the Java Web Start Administration Tool web interface as shown in figure 2.7.
At the top you notice the URL that should be entered into the bugsubmission.properties
file. Using the URL in figure 2.7 as example, the property file should look like this:

url = http://localhost:9090/WebStartAdministration122/bugreport/

Whenever a bug submission is received, an email can be sent from the Java Web Start
Administration Tool if all the email settings are filled in. Multiple receivers can be specified by
separating them with commas. If the string properties-username is entered in any of the
receiver or sender address fields, it will be replaced with the operating system username from
the bug submission.
By default each bug submission is saved to the system tmp folder. Below the mail settings
CHAPTER 2. JAVA WEB START 17

Figure 2.7: Configuration of how bug submissions should be handled.

fields, you can enter a path to a Backup directory which will then be an alternate place to save
each bug submission. This should be an absolute path.
When the workbench starts up it is written in the log where the bug submission is directed to.
There is a test email config button and test backup directory button at the very bottom of the
page.
Chapter 3

Installation without Java Web Start

This chapter deals with the installer and related information about the installation process when
using the standard installers rather than Java Web Start.

3.1 Available installers

There are installers available for each platform (Windows, Mac OS X and Linux). Each of these
installers is available in a 32-bit and a 64-bit version, except for the Mac OS X installer. For
Linux, there is both a .sh installer and an .rpm package.

3.1.1 Java
The Workbenches are based on Java, and this means that there has to be a Java Runtime
Environment (JRE) on the computer to run the Workbench. For both Linux and Windows, the
installers have a built-in JRE that will be installed in the installation directory of the Workbench.
The advantage of this is twofold:

1. For computers who do not already have a JRE installed, the need for downloading and
installing a JRE is eliminated.
2. For computers who already have a JRE installed, there will never be compatibility problems
because the Workbench always uses its own JRE.

The built-in JRE is the latest Java 6 JRE from Sun Microsystems (http://java.sun.com).
The JRE used for running the CLC Workbench will not interfere with existing JREs on the computer.

Java on Mac
Since the Workbench uses Apple's JRE, there is no JRE included in the installer. When running
the Workbench on 64-bit systems, please make sure that the 64-bit Java is used for launching
applications:
Go to /Applications/Utilties/Java and double click on Java Preferences. In the Java
application versions, reorder the list to have JRE6/64 bit at the top. Note that this may change
the behavior of other Java-based programs on the computer.

18
CHAPTER 3. INSTALLATION WITHOUT JAVA WEB START 19

Note! After setting the Java preference, you can either uninstall and reinstall the workbench
and the memory will be adjusted automatically, or you can set the memory yourself (see section
10.1).

3.1.2 Overview of available installers

The table below shows an overview of the installers that are available.

Platform JRE included Special 64-bit version

Windows (2000, XP , Vista, 7 and 8) Yes Yes
Mac OS X 10.6 or later. 1 No No
Linux installer Yes Yes
Linux package Yes Yes

3.2 What does it do?

The installer performs the following tasks:

3.2.1 Extracting and copying files to the installation directory

The Workbench is installed into the following directory per default (we use CLC Main Workbench
6 as example):

Windows C:\Program files\Main Workbench 6

Mac OS X Applications/Main Workbench 6

Note that each major version of a Workbench has its own installation directory. This means that
when upgrading from e.g. CLC Main Workbench 5 to CLC Main Workbench 6, the old installation
directory of version 5 will be left untouched when you install CLC Main Workbench 6.
If you wish to remove the old installation, please run the Uninstall program.
Minor updates will use the existing installation directory of the Workbench.
The installation directory can be defined during installation - the above are the default installation
directories (see section 3.3 for more information on how to define the installation directory).

3.2.2 Setting the amount of memory available

The installer investigates the amount of RAM during installation and sets the amount of memory
that the Workbench can use. Read more in section 10.1.

3.2.3 Shortcuts and file associations

The installer also creates shortcuts for starting the Workbench, and it creates file associations
so that .clc files will be opened by the Workbench.
CHAPTER 3. INSTALLATION WITHOUT JAVA WEB START 20

3.3 Silent installation

The installer also has a silent installation mode which is activated by the -q parameter when
running the installer from a command line, e.g.
CLCMainWorkbench_5_6.exe -q
On Windows, if you wish to have console output, -console can be appended as the second
parameter (this is only needed when running on Windows where there is no output per default):
CLCMainWorkbench_5_6.exe -q -console
You can also in silent mode define a different installation directory: -dir.
CLCMainWorkbench_5_6.exe -q -console -dir "c:\bioinformatics\clc"
Note! Both the -console and the -dir options only work when the installer is run in silent
mode.
The -q and the -console options work for the Uninstall program as well.
Chapter 4

License

There are fundamentally two kinds of licenses for the Workbenches:

Fixed license A license order ID has to be activated against our server for each computer. The
license will then be fixed to this computer. This requires manual intervention for each
activation.

Floating license A license server is installed in your organization. It hosts a number of licenses
which can be shared among all computers. Note that the license server is available for
both Linux, Windows and Mac OS X.

For large installations, the floating license is by far the best option, since all the license
administration takes place on the server (find the manual for the license server together with the
server distribution). The fixed license requires manual work during installation and also if the
licenses need to be updated.
For information on how to use the floating license, please refer to the user manual for the relevant
Workbench (see http://www.clcbio.com/manuals).
Plug-ins use the same licensing system as the Workbenches, so all the concepts described here
also apply to the plug-in licenses.

4.1 License server set-up on clients

The connection to the license server can be set up as described in the Workbench user manual
(see also figure 4.1).
The license server information is stored in a file called license.properties in the settings
folder in the Workbench installation directory. This means, that you need write access to the
installation directory (with the default installation directory, you need to be an administrator to
have this write access) in order to set up a connection to the license server. The file contains
the following:

21
CHAPTER 4. LICENSE 22

Figure 4.1: Connecting to a license server.

serverip=
serverport=6200
disableborrow=false
autodiscover=true
useserver=true

Since all this information is stored in a file in the installation directory, it can easily be copied
to all clients, and the license configuration is completed. When the Workbench is started, it will
look in this file, and if useserver=true then it will try to connect to the license server, and no
license dialogs will be shown to the user.
You can download a sample license.properties file at http://clcbio.com/files/
deployment/license.properties.
Chapter 5

Plug-ins and resources

There is a graphical user interface to install plug-ins called the Plug-in Manager ( ) which is
invoked in the Help menu (see figure 5.1).

Figure 5.1: The Plug-in Manager.

Plug-ins are either general modules or extensions provided by CLC bio (see http://www.
clcbio.com/plugins) or can be custom-made plug-ins specific to your organization.
Plug-ins can either be downloaded and installed directly in the Plug-in Manager, or they can be
installed from a file Install from File button at the bottom of the Plug-in Manager.
Resources are installed in the same way as plug-ins. Resources can be e.g. PFAM databases
used by the Workbench's PFAM Domain Search ( ).
Installing a plug-in is basically just a matter of putting files in the right folder. All plug-in files are
put in plugins and all resources in resource in the installation directory. This means that
the contents of these folders can be copied to other computers, and they will have the plug-ins
installed.
Licenses for the plug-ins are handled the same way as the Workbench licenses, see section 4.

23
Chapter 6

Workflows

There is a graphical user interface to install workflows called Workflows ( ) which is invoked in
the Help menu (see figure 6.1).

Figure 6.1: The workflow manager.

Workflows can be created in any workbench and distributed as an installer file that can be
installed in any workbench or server.
A workflow is always installed per user. The workflow definition is stored in the user home (see
section 11.3).
The ability to install workflows can be disabled by the policy (see section 8).
When the workbench is part of a CLC Genomics Server set-up, it will be a great advantage to
manage workflows to be used by all users on the server which means no local deployment
when workflows are updated (see more in the user manual at http://www.clcbio.com/
usermanuals).

24
Chapter 7

Connecting to a CLC Server

Information about server name and port can be stored in a file called serverinfo.properties
in the settings folder in the Workbench installation directory. When the user opens the log-in
dialog, the Workbench will read in the information from this file.
If the file does not exist, the information that the user enters will be saved in the user settings.
The user name and password is stored with the user settings.
The serverinfo.properties file contains the following:

port=7777
host=hostname

Since all this information is stored in a file in the installation directory, it can easily be copied to
all clients.
You can download a sample serverinfo.properties file at http://clcbio.com/files/
deployment/serverinfo.properties.

25
Chapter 8

Security policies

The Workbench has a security policy configuration that enables administrators to restrict users'
access to:

• Tools accessing services on the internet. This includes NCBI BLAST, NCBI and Uniprot
Searches.
• Notifications about updates. Update notifications on new Workbench and plug-in versions
• Plug-in management. Installation of plug-ins.

The configuration is specified in a simple properties file called policy.properties that

resides in the settings folder of the installation directory (e.g.
C:\Program Files\CLC Main Workbench 6\settings on Windows). Note that users
without administrator access will not be able to change the contents of this file. Each of the
following keys can be followed be either allow or deny:

workbench_version_check Controls whether notifications for Workbench updates should be

shown.
plugin_version_check Controls whether notifications for plug-in updates should be shown. Note
that if plugin_download is not allowed, plug-in update notifications will not be shown,
regardless of this setting.
online_ncbi_search Controls whether the Search for Sequences at NCBI ( ) in the Download
menu should be available (this can be used to search for and download sequences from
NCBI).
online_structure_search Controls whether the Search for Structures at NCBI ( ) in the
Download menu should be available (this can be used to search for and download
3D structures from NCBI).
online_uniprot_search Controls whether the Search for Sequences in UniProt ( ) in the
Download menu should be available (this can be used to search for and download
sequences from Swissprot/UniProt).
online_ncbi_blast Controls whether all the tools performing BLAST at NCBI's servers should be
available. This is NCBI BLAST ( ) both from the Toolbox and from sequence selections.

26
CHAPTER 8. SECURITY POLICIES 27

plugin_manage Controls whether the Plug-ins and Resources manager should be available for
the user. Note that users can still install plug-in updates if plugin_download and
plugin_version_check are allowed.

plugin_file_install Controls whether this user should be allowed to install plug-ins and resources
from a local file.

plugin_download Controls whether this user should be allowed to install CLC plug-ins and
resources downloaded directly within the plug-in manager dialog. This also includes
manually checking for updated plug-ins in the Plug-ins and Resources manager dialog and
also the automatic check for plug-in updates at start-up.

workflow_file_install Controls whether the user should be allowed to install workflows from a
file.

workflow_manage Controls whether the user should be allowed to manage workflows.

workflow_download Controls whether the user should be allowed to download and install
workflows form the CLC workflows repository.

Per default, there is no policy.properties file, so everything is allowed. A commented sample

file that you can download and edit is located at http://clcbio.com/files/deployment/
2/policy.properties. Download the file and place it in the settings folder, update the
relevant values, and the new policy will take effect next time the Workbench is started.
Chapter 9

Storing and backing up data

This chapter explains how data is stored, gives general guidance on size of data, and outlines
configurations needed for running analyses on large amounts of data.

9.1 Storing data

9.1.1 Data structure
The data in the Navigation Area is organized into a number of Locations. When the the CLC
workbenches except the CLC Genomics Workbench is started for the first time, there is one
location called CLC_Data (unless your computer administrator has configured the installation
otherwise).
A location represents a folder on the computer: The data shown under a location in the Navigation
Area is stored on the computer in the folder which the location points to.
This is explained visually in figure 9.1. The full path to the system folder can be located by
mousing over the data location as shown in figure 9.2.

Figure 9.1: In this example the location called 'CLC_Data' points to the folder at C:\Documents and
settings\clcuser\CLC_Data.

28
CHAPTER 9. STORING AND BACKING UP DATA 29

Figure 9.2: Mousing over the location called 'CLC_Data' shows the full path to the system folder,
which in this case is C:\Users\boester\CLC_Data.

If the Workbench is connected to a CLC Server, the server's locations will automatically show up
when the user is logged in. This chapter does not deal with server locations - please refer to the
server user manual at http://www.clcbio.com/usermanuals.
The list of locations is stored in a file called model_settings_300.xml in the settings
folder in the user home (see section 11.3). We do not recommend manual editing of this file,
although it is standard xml.

9.1.2 Changing the default location

In some set-ups, storing data in the default location CLC_Data in the user home is not desired.
This could be for roaming user profiles or in situations where there is a quota on this disk.
The default location that is used the first time the Workbench starts can be configured in the
path.properties file that resides in the settings folder of the installation directory (e.g.
C:\Program Files\CLC Main Workbench 5\settings on Windows). Add a line like this
to the file to change the default location: The file should include one line like this:

datadir = c:\clcdata

The following variables can be used to construct the path to the desired location:

$user the user name of the current user

$home the home directory of the current user

$product the short name of the workbench (example: clcgenomicswb or clcmainwb)

A few examples:

datadir = $home/CLC_Data (default)

datadir = X:\clcstorage\$user (seperate disk / network mount in Windows)

Note that the folder does not need to exist - it will be created if needed. You can use both slash
(normally used on Mac and Linux) and backslash (normally used on Windows) in the configuration
file - the Workbench will use the appropriate one depending on the platform.
Note that the default location is only considered the very first time the Workbench starts. When
the Workbench closes the first time, the model_settings_300.xml file is created and this is
where it will look for the locations further on. Deleting this file will make the Workbench look for
CHAPTER 9. STORING AND BACKING UP DATA 30

the datadir property in the path.properties file. The model_settings_300.xml file is

located in the settings folder in the user home (see section 11.3).
You can download a sample path.properties file at http://clcbio.com/files/deployment/
path.properties.

9.2 Back-up of data

Since all data used in the Workbench is stored as files in the locations specified, a back-up
procedure has to include all the locations. If the data needs to be restored from a back-up,
simply copy the files back into the folder locations and start the Workbench.
Database locations needs a different back-up procedure.
Besides the data itself, user-level settings should also be included in the back-up (see section
11.3).

9.3 Special configurations for large amounts of data

Especially the CLC Genomics Workbench is often used with large amounts of data. This means
that special configurations often need to be made. This concerns locations for temporary data
and disk space in general.

9.3.1 Temporary data

The Workbench has a built-in cache system that intends to make sure that the Workbench does
not run out of memory even for large data sets. During various processes such as assembly and
RNA-Seq analysis, the Workbench often writes temporary files to the disk. Depending on the data
set, these temporary files can take up a lot of disk space.
If there is not enough space in the default tmp directory, the tmp directory can be re-directed:
Create a text file called path.properties and save it in the settings folder in the Workbench
installation directory. Please ensure this file does not have a ".txt" extension. The file should
include one line like this:

tmpdir = /path-to-temp

Instead of "/path-to-temp" you write the absolute path to the new tmp directory. When the
Workbench is restarted, it will then use the new directory for storing temporary data.
You can download a sample path.properties file at http://clcbio.com/files/deployment/
path.properties.
Note! It is imperative for acceptable performance that data transfer to the temp directory is not
over a network connection. Since the Workbench will spend a lot of time writing and reading
these files, disk speed has a great impact on overall performance when working with large data
sets.
CHAPTER 9. STORING AND BACKING UP DATA 31

9.3.2 Disk space requirements

It is hard to give general guidance on disk space requirements, but we have made an example of
a typical work flow for CLC Genomics Workbench to illustrate.
For calculating disk space for next-generation sequencing data you need to consider the following:

• Reads are imported and take up space as raw reads (see details below). Once imported,
you can delete the original sequence file if you do not need it for other purposes.

• When the data has been assembled, either de-novo or against a reference, they take up
space once again (this time more space since there is also information about where they
map etc).

• Reference sequences also take up space.

• The computer doing the analysis needs space for tmp files. Once the assembly is done,
the temporary files are deleted. The temporary files usually do not take up more space than
the final result

The formulae giving the disk space usage:

Bytes per read: 28 + (length of read name) + 0.25 x (length of read)
Note that you can discard read names during import.
If quality scores are present, add: 6 + (length of read)
If color space encoding is present, add: 7
As an example, a data set of 5.2 million 35 bp reads imported by CLC Genomics Workbench
using the Discard sequence names option including quality scores takes up:
5,244,764 x ( (28 + 0 + 0.25 x 35) + (6 + 35) ) = 389 MB
When mapped to a 4.7 Mbp annotated reference sequence, the mapping results takes up 473
MB.
Chapter 10

System resources

You can specify the amount of system resources that the Workbench is allowed to use. This can
be done for both memory and CPU.

10.1 Setting the amount of memory available for the JVM

When running the Workbench, the Java Virtual Machine (JVM) needs to know how much memory
it can use. This depends on the amount of physical memory (RAM) and can thus be different from
computer to computer. Therefore, the installer investigates the amount of RAM during installation
and sets the amount of memory that the JVM can use when running the Workbench. When using
Java Web Start, this needs to be set in the profile (see section 2.5), and separate profiles need
to be created if there is not one memory setting that will fit all Workbench computers.
On Windows and Linux, this value is stored in a property file called workbenchname.vmoptions
(e.g. clcmainwb.vmoptions) which contains a text like this:

-Xmx1400m

The number (1400) is the amount of memory the Workbench is allowed to use. The file is placed in
the installation folder (e.g. C:\Program Files\CLC Main Workbench 6\clcmainwb.vmoptions).
On Mac OS X, the -Xmx value is stored in Info.plist in the application bundle (Control-click
the application and choose "Show Package Contents").
The value is set to 50% of the computers RAM per default, and at a maximum of 1400 MB for
32-bit systems and a maximum at 50GB for 64-bit systems (at this point there is no performance
increase by setting it higher because of overheads in memory management). If you do not wish
to use the installer on each computer and use an image instead, either make sure all computers
have the same amount of RAM, or set the number to 50% of the computer with the smallest
amount of RAM (this value should not be lower than 200 MB, and for genomics-scale data, it
should be significantly higher).
You can manually change the contents if you want to raise or lower this value. In case you get
an out of memory error you may need to allocate a higher amount of memory by increasing the
number in the .vmoptions file. In case you get a java exception saying "The JVM could not be
started. The main method may have thrown an exception" you may need to decrease the value
in the .vmoptions file.

32
CHAPTER 10. SYSTEM RESOURCES 33

10.2 Setting the number of cores to use

A number of the algorithms in the CLC Genomics Workbench , in the case of large jobs, use all
the cores available on your system to make the analysis as fast as possible.
If you wish to restrict this to a predefined number of cores, this can be done with a properties file:
Create a text file called cpu.properties and save it in the settings folder in the Workbench
installation directory. The file should include one line like this:

maxcores = 1

Instead of 1 you write the maximum number of cores that the Workbench is allowed to use.
When the Workbench is restarted, it will comply with this setting. Please note that this is not a
guarantee that the Workbench will never use more, but that will be for very brief and infrequent
peaks and should not affect performance of other applications running on your system. The only
exception is when a user starts several jobs to run simultaneously.
You can download a sample cpu.properties file at http://clcbio.com/files/deployment/
cpu.properties.
Chapter 11

Overview - where do we put things?

This part gives you an overview of all the parts of a CLC Workbench installation. Some parts are
at the level of the computer, i.e. shared by all users, whereas other parts are at the user level.

11.1 Computer-level information

In the Workbench installation directory, you will find the following:

Licenses The license information depends on what kind of license you use:

Fixed licenses Stored in the licenses folder (they are unique for each computer)
Floating licenses Information about the license server connection is stored in the license.properties
file in the settings folder.

Plug-ins are stored in the plug-ins folder and can be copied to other computers running the
same version of the Workbench.

Resources are stored in the resource folder and can be copied to other computers running the
same version of the Workbench.

Memory allocation for the VM is stored in the workbenchname.vmoptions file.

Various property files are stored in the settings folder. See a full overview in section 11.2

In addition, file associations for .clc files are stored in the registry database on Windows.

11.2 Property files overview

The following property files are all stored in the settings folder of the Workbench installation,
and can be added to a profile when using Java Web Start (see section 2.5.3).

policy.properties for specifying if certain options should be removed from the Workbench (see
section 8).

path.properties for specifying default data location (see section 9.1.2) and where to store
temporary data (see section 9.3.1)

34
CHAPTER 11. OVERVIEW - WHERE DO WE PUT THINGS? 35

serverinfo.properties specify host and port for connecting to a CLC server (see section 7).

proxy.properties holds information about proxy server (when the Workbench needs access to
online services). Read more in the Workbench user manual at http://clcsupport.com/
clcgenomicsworkbench/602/index.php?manual=Network_configuration.html

license.properties holds information about the host and port of a license server that should be
used (see section 4.1).

cpu.properties specifies the maximum number of cores to be used by the Workbench (see
section 10.2).

bugsubmission.properties specifies the server to receive bug reports. You need to use the Java
Web Start Administration Tool to be able to use this feature (see section 2.6).

11.3 User-level information

The user-level information is found in the application data folder:

Windows 2000 and XP C:\Documents and settings\username\Application data\CLC bio

Windows Vista, 7 and 8 C:\Users\username\Appdata\Roaming\CLC bio

Mac OS X User home/Library/Application Support/CLC bio

Linux $HOME/.clcbio

In this folder, the following information may be useful to you:

User settings The user settings file stores information such as view settings, parameters,
workspaces, user name and password to server log-ins and other settings customized
by the user. The user settings file is found in the application data folder under
settings/workbench name/version name. It is recommended to back up the
user settings file. When upgrading to a new version of the Workbench, the user's old user
settings file is copied by the Workbench the first time it is run.

Locations Information about which locations the user has added in the Navigation Area is stored
in the model_settings_300.xml file in the settings folder.

Error logs to be sent to [email protected] for use in case of program errors are output.log
and error.log and they are found in the log folder.

Workflows Workflows are saved in a workflows/workbench name/version name folder.

When upgrading to a new version of the Workbench, the user's old workflows are copied
by the Workbench the first time it is run, unless there are major changes to the workflow
framework that breaks compatibility. Note that if you are using a CLC Genomics Server
or CLC Science Server, it will be more convenient to deployed and maintain workflow
installations on the server rather than on the Workbench.
Appendix A

Appendix

A.1 Java Web Start troubleshooting

A.1.1 Cannot start Workbench when offline
With Java 7 update 21, a bug was introduced preventing the Workbench to start when off line, see
http://www.oracle.com/technetwork/java/javase/7u21-relnotes-1932873.html.
The work around is to either:

• Launch Javaws explicitly from a command line using javaws -offline <jnlp_url>

• Launch the cached application via Java Cache Viewer, see http://docs.oracle.com/
javase/tutorial/deployment/webstart/running.html#cache

36
Index

CLC Bioinformatics Database, 6 for plug-ins, 21

CLC Server, 6 Linux, 6
32-bit installer, 18 Linux installer vs. package, 18
64 bit installer, 18 Locations, 35

Back up Memory allocation, 32

user settings, 35
Back-up, 30 Online tools, block access to, 26
Block access to internet, 26 Output log, 35

Command-line installation, 20 Plug-in licenses, 21

Cores, restrict usage, 33 Plug-in Manager, 23
CPU, restrict usage of, 33 Plug-ins, 23
Policy, 26
Data storage, 28
Data structure, 28 Quiet installation, 20
Database
RAM, 32
local, 28
Resources, 23
Error log, 35 .rpm, Linux package, 18

Floating license, 21 Security policies, 26

Server connection, 25
GHOST image, 7 .sh, Linux installer, 18
Silent installation, 20
Image, copy, 7 System requirements, 7
Install System resources, 32
plug-ins, 23
resources, 23 Temporary data, 30
workflows, 24
Installers, overview, 19 User settings, 35
Introduction, 6
VM, Virtual Machine, 18
Java, 18 .vmoptions, memory allocation, 32
Java Web Start, 10
Workflows, 24
JNLP, 12
JRE, Java Runtime Environment, 18 Xmx argument, 32
JVM, Java Virtual Machine, 18

License order ID, 21

License server, 21
set-up on clients, 21
Licenses, 21

37