If you are a Managed Hosting customer, this topic doesn't apply to you.

This section reviews the configuration steps necessary before installing Blackboard Learn. The following instructions apply whether the server architecture uses one, two, or multiple, load-balanced servers. Differences in process per operating system, database, or architecture are noted.

Application servers should be dedicated to Blackboard Learn for optimal performance. Make sure that the server is not using valuable space and resources running unnecessary applications.

A load-balanced configuration requires that the first application server, shared content directory, and database server be installed using the two server configuration model. After that, the installer can be run again on each additional application server to install only the application components. Each additional application server must also meet the required prerequisites.

If using the Collaboration server it must be installed on a single server that is not served as part of a load-balanced configuration. The Collaboration server may not be spread across multiple application servers because all users participating in a collaboration session must share the same resources. A single server must be configured to run the Collaboration server. This server must handle collaboration sessions and performance will be unaffected by other requests. The application servers are configured to connect users to one server that handles all the collaboration sessions.

Required hardware

Hardware sizing information for Windows or Linux Dell Environments and Hardware sizing information for UNIX Sun Environments detail several different hardware configurations based on performance, cost, and redundancy. Use these reference documents to ensure that the planned hardware configuration meets the needs of the institution.

SPARC hardware was required to install and run Blackboard Learn under Solaris operating systems. Blackboard Learn no longer supports application servers running Solaris. For more information, visit Behind the Blackboard.

Load balancing methods

Institutions can use the load balancing method of their choice as long as it adheres to a few basic principles:

  • The load balancing method must use cookie-based session affinity.
  • TLS certificates need to be exposed to clients whether via load balancer TLS-offloading or certificates on each application server. TLS-offloading is the recommended installation in a load-balanced configuration.
  • The installation value used for the machine hostname (bbconfig.frontend.fullhostname) must be resolvable and fully accessible from each application server.

To learn more about load balancing configuration and options, see Load Balancing - Configuration and Best Practices. Understanding the load balancing options are essential for proper configuration of Blackboard Learn behind a load balancer.

Required software and setup

For the exact versions of the operating systems, databases, and Java SE Developers Kit (JDK™) that are supported, see Supported Technologies for your release. It is critical that the software used to host Blackboard Learn meets requirements.

After selecting and installing the operating system, proceed with installing the Java Virtual Machine on the application server.

Java Virtual Machine

Download the supported version of the JDK at the Oracle website. The JDK must be downloaded and installed on each application server.

After you install the JDK, you may simplify future upgrades to Java and minimize impact on Blackboard Learn configuration by creating a soft link of the installed JDK named 'latest_java'. For example: use /usr/java/latest_java instead of using /usr/java/jdk1.7.0_51 where latest_java is a link to the latest installed Java Virtual Machine.

If you installed UNIX with a non-Oracle JDK (e.g. OpenJDK), you should either uninstall OpenJDK or use the alternatives tool for selecting the Oracle JDK after installation.

Set JAVA_HOME (optional)

The JAVA_HOME environment variable may be set, but is not required for application installation or operation.

Not setting JAVA_HOME will require full paths to the installed Java tools. For example: # /usr/local/jdk/bin/java -jar bb-installer.jar instead of # java -jar bb-installer.jar

Make sure that the path to the JDK does not include any spaces. For example, do not use C:\Program Files\Java\jdk1.7.0.... Instead, use C:\Java\jdk1.7.0....


The JAVA_HOME variable may already be set. This may be confirmed via:

Printenv | grep JAVA_HOME

Create an environment variable that points to the JDK installation directory and call it JAVA_HOME. Add $JAVA_HOME/bin to the system path to be able to run javafrom the command line. You can do this by adding the following lines to the .bashrc file in your home directory.

In this example /usr/java/jdk1.7.0_51 is the JDK installation directory.

vi ~/.bash_profile
export JAVA_HOME=/usr/java/ jdk1.7.0_51
export PATH=$PATH:$JAVA_HOME/bin

If you have more than one version of JVM installed in your machine, make sure you are using the supported JDK installation as the default java and javac.


Follow these steps to set the JAVA_HOME environment variable:

  1. Make sure that the correct version of the JDK is installed on the application server.
  2. Right-click Computer and select Properties.
  3. Select Advanced System Properties.
  4. Select Environment Variables.
  5. In the system variables list, find JAVA_HOME and select Edit. If JAVA_HOME does not exist in the system variables list, select New. A pop-up window will appear. The Variable name should read JAVA_HOME.
  6. Enter the full path to the JDK in the Variable value field. For example, C:\Java\jdk1.7.0_51.
  7. Select OK.

Select paths for Windows versions may vary from the steps presented here.

More on how to set environment variables for your 2008/2012 Windows Server

Create system user accounts

Blackboard Learn requires operating system accounts for installation and operation. You create these using the tools provided by the operating system.


The UNIX system user account must be created prior to installation with the following parameters.

  • The user name must be bbuser.
  • The bbuser account must have a valid home directory.
  • Blackboard recommends using /home/bbuser for Linux operating systems.


Create a domain user (for example, "blackboard") that will have access to the application server, the file server, and the database server. This user must be part of the Administrators group throughout the setup and installation. After this user is created, use it to log in to the servers.

Confirm file system


On UNIX systems select a suitable file system such as ext4. Each application server should use the same file system type.


On Windows operating systems, Blackboard Learn requires the use of NTFS as the file system. Follow the steps below to confirm that the disk is using the NTFS file system.

  1. Double-click My Computer on your desktop.
  2. Right-click the drive where Blackboard Learn will be installed.
  3. Select Properties.
  4. The File system field must display NTFS. If it displays anything other than NTFS, consult the operating system documentation for steps to convert the drive to NTFS.
  5. Repeat these steps on each application server, the database server, and the file system server.

Dedicated file system server

In a load-balanced system, if not using a SAN, maintain one server as a dedicated file system server. The Blackboard Learn content files must be centralized so that all files are available to users regardless of the application server handling the connection. The application servers are configured to find the content files in a directory on the file system server.

Network file share and common internet file system

For connecting external storage to Blackboard Learn application servers, clients should use the Blackboard supported file system sharing model for their selected operating system:

  • UNIX platforms should use a network file share (NFS).
  • Windows platforms should use a common internet file system (CIFS).

More on how to set up file system storage

Synchronize server clocks

Check the date and time on the system and make sure it is accurate and that the time zone is set correctly. If installing on two servers, check that the time on the application server and database server match. Remember that the servers may be in a different time zone than users. The server time zone should be the same as the time zone used by the majority of users, instead of the physical location of the server. Blackboard Learn uses the server date and time to control the availability of time-sensitive materials. It is important that users have a clear expectation of when materials will be available and when assignments are due.


The Network Time Protocol daemon (ntpd) program is a Linux operating system daemon. It sets and maintains the system time of day in synchronism with time servers (milliseconds). You need to configure ntpd via /etc/ntp.conf configuration file.

Install ntpd

If ntpd is not installed, use any one of the following command to install ntpd:
# yum install ntp or # up2date ntp


You should at least set following parameter in /etc/ntp.conf config file:
server <Time Server Name or IP Address>

  1. For example, open /etc/ntp.conf file using your editor of choice
  2. Locate the server parameter
  3. Enter server pool.ntp.org
  4. Save the file and restart the ntpd service:

    # /etc/init.d/ntpd start

  5. You can synchronize the system clock to an NTP server immediately with following command:

    # ntpdate pool.ntp.org


Windows clients can synchronize their clocks with an external source. Visit Microsoft's website for more information.


Keep in mind the following when connecting Blackboard Learn to the network:

  • Don't use underscores in the machine name for the server or servers. Some versions of Internet Explorer block cookies if the machine name includes an underscore.
  • Check with a network engineer to make sure that the network can handle the anticipated load after Blackboard Learn is made available to users.
  • An SMTP server must be available so that the installer can connect to it.
  • An SMTP server has to remain available when the application is running to deliver email notifications.
  • Set up the DNS server to resolve the hardware load-balancer. The hardware load balancer will then direct traffic to the application servers. Set up a separate DNS entry for the Collaboration server.


Blackboard Learn requires ports to communicate. In this section, we list the required ports for initial installation and their default values. Make sure to configure server security and any firewalls to allow communication on these required ports. The port values must be the same for each application server.

Depending on post-installation choices, additional ports and port related configuration may be required. These are outlined in the Post-Installation and Upgrade section:

Set Up Load Balancing (Multiple Application Servers)

Front Learn with a Webserver (For CAS or Shibboleth)

Blackboard Learn-only ports

  • Tomcat port (default value: 8080): This port handles non-secure communication to/from the load-balancer if TLS is off-loaded at the load balancer.
  • Tomcat TLS port (default: 8443): This port is the primary secure web application port if TLS is not off-loaded

Out of the box Blackboard Learn-only receives requests on ports 8080 and 8443 and by default is accessible via http://learnserver:8080 and https://learnserver:8443.

To provide default URLs that require port information appended, you must route incoming port 80/443 requests to 8081/8444, respectively. See Set Up Port Forwarding (Single Application Server) for steps to make the Blackboard Learn-only server available on default ports after install or upgrade.

Web server ports

  • Web server port (default value: 80): This port handles communication for legacy non-secure connections when a web server is in use. Users will be forwarded to a secure port.
  • Web server TLS port (default: 443): This port is the primary secure web server port when a web server is in use.

Ports 80/443 may be closed if not using a webserver.

Single server specific ports

  • SQL Server Listener port (default value: 1443): This port connects to a database in a Windows environment.
  • Oracle TNS Listener port (default value: 1521): This port connects to a database in a UNIX environment.

Collaboration server ports

These ports must be open if the server is being used as a Collaboration server.

  • Collaboration server TCP/IP port (default value: 8010): This port handles primary TCP communication for the Collaboration server. By default, TCP communication connects users to the Collaboration server.
  • Collaboration server HTTP port (default value: 8011): This port handles HTTP communication for the Collaboration server and is configured for legacy reasons, but does not receive traffic in Blackboard Learn 9.1 April 2014 and later releases.
  • Collaboration server TLS port (default: 8012): This port handles HTTPS communications for the Collaboration server for downloading the applet. Note: this was previously 8443 and must be changed in bb-config.properties prior to upgrade!

Any port higher than 1024 must be open between the application servers so that they can communicate through the peer services framework.

Configure SQL Server Agent Automatic Startup

SQL Server client tools needs to be installed on each application server.

The SQL Server Agent must be running and set to Automatic startup for Blackboard Learn where %INSTANCE% is the name of the database instance (blank for a default instance).

  1. Right-click Computer and select Manage.
  2. From the Server Manager, select Configuration, and then select Services.
  3. Right-click SQL Server Agent (instance) and select Properties.
  4. From the Startup type, select Automatic.
  5. Select OK.