Skip navigation
All Places > Blackboard Developer Community > Blog > 2019 > February
2019

Let me start by saying how much I appreciate the Developer Virtual Machine and the work that Blackboard has put into optimizing the install and upgrade process of Learn.

 

Unfortunately, I cannot use the DVM directly on my machine because I already have Hyper-V in use. It would require bcdedit & a reboot to toggle hypervisors.

 

To get going "quickly," I used VirtualBox's tools to convert the .vmdk to a .vhd. Then I manually attached the hard disk to a custom VM in Hyper-V. It works perfectly with the exception of shutting down/rebooting. The VM has to be reset again to get the bootloader to fire. My DVM eventually needs to be rebooted after repeatedly deploying a building block.

 

Our production and test environments are inside Blackboard's managed hosting, so going into this I had 0 experience with the server-side operations of Learn.

 

Once my project was done, I started to get curious. Now that I'll need to test my building block regularly, how do I install a signed certificate so that testers' browsers stop complaining?

  • The official documentation briefly goes over installing a signed certificate on a single-server install, but it leaves out the fact that the keystore password is now encrypted.

The DVM available was out of date. How do I upgrade it?

  • The upgrade process requires an installer.properties that was not left behind by the creator of the DVM. I found a blog post Upgrade Your DVM that includes everything you need to upgrade to the latest Learn version.

 

Ultimately the DVM is designed to be a throw-away install, but I need it to last longer and be a tad more secure. So I've documented the install process from scratch.

 

You will need:

 

RHEL 7.5 is a supported operating system, and I am familiar with it, so I am using CentOS.

 

You will also need a way to transfer files to the server. There are several ways including using scp, wget from a [local] server, mounting a share, or configuring samba.

 

With the hard drive capacity set to 20 GB, it will be 52% full after Learn installation. If you delete the installer.zip, it will be 43% full. If you delete the installer directory, it will be 27% full.

 

(Scenario A) Hyper-V Virtual Machine Setup

 

I use Hyper-V Manager on Windows 10 Pro.

 

Manually create a new Virtual Machine

  • under Specify Generation: select Generation 2
  • under Assign Memory: set 4096 MB, DISABLE the option "Use Dynamic Memory for this virtual machine"
  • under Configure Networking: select external switch
  • under Connect Virtual Hard Disk: create a virtual hard disk with 20 GB
  • under Installation Options: select Install an operating system from a bootable image file, and select .iso

 

Edit the newly created VM Settings

  • under Security: DISABLE the option "Enable Secure Boot"
  • under Processor: increase the "Number of virtual processors" (at least 2)
  • under Network Adapter: verify settings are correct (I need to set a VLAN id in my environment)
  • under Checkpoints: DISABLE the option "Use automatic checkpoints" - unless you want them!

 

(Scenario B) vSphere 6.5 (ESXi) Virtual Machine Setup

 

Manually create a new Virtual Machine

  • under Select a guest OS: select "Linux" family, select "CentOS 7 (64-bit)" version
  • under Customize hardware:
    • CPU: 2, cores per socket
    • Memory: 4 GB
    • New Hard disk: 20 GB
    • New Network: as needed
    • New CD/DVD Drive:
      • if you uploaded the iso to a datastore, select Datastore ISO file and ENABLE the option "Connect At Power On"
      • otherwise, select Client Device - you must manually connect the iso from the remote console

 

Starting the server build

 

Start the VM

  • The iso's bootloader should fire. You might have to play with the boot order.
  • Select Install CentOS 7

 

CentOS installer

  • under Network & Host Name:
    • click ON to enable Ethernet
    • set the Hostname if desired - make sure you click apply
  • if you are not using the Minimal installer iso:
    • under Software Selection: select Minimal Install

 

During install

  • under Root Password:
    • set Password as needed
  • under User Creation
    • set "Full name" to bbuser
    • set "User name" to bbuser
    • ENABLE the option "Make this user administrator"
    • set Password as needed

 

Reboot

 

Post OS install

 

If you need to manually set a static IP, using the console, login as bbuser

$ sudo nmtui

  • Edit a connection
    • set IPv4 - manual (did not test with IPv6 - ignore)
  • Activate a connection
    • toggle state for IP changes to take affect immediately

 

Login as bbuser using SSH

 

(optional) configure the wheel group to not require a password for sudo

$ echo '%wheel ALL=(ALL) NOPASSWD: ALL' | sudo tee /etc/sudoers.d/wheel

 

Update to the latest packages

$ sudo yum update -y

 

Install the needed packages

$ sudo yum install open-vm-tools wget unzip postgresql-server postgresql-contrib policycoreutils-python

 

Transfer the latest Oracle JDK 8 for Linux x64 rpm to server (can be deleted later to reclaim space)

 

Install the jdk8 rpm

$ sudo yum localinstall jdk-8uXXXXX-linux-x64.rpm

 

Add a missing shared library for Java (the rpm does not include the link).

  • You can confirm this by running $ ldd `which java`

$ echo '/usr/java/latest/jre/lib/amd64/jli' | sudo tee /etc/ld.so.conf.d/java.conf; sudo ldconfig

 

Add JAVA_HOME (not required, but recommended) and PGDATA (required, location of DB) to default environment

$ echo -e '#!/bin/bash\nexport JAVA_HOME=/usr/java/latest\nexport PGDATA=/usr/local/bbdata' | sudo tee /etc/profile.d/bb-environment.sh

 

(optional) prepare for publickey auth

$ mkdir --mode=750 ~/.ssh; touch ~/.ssh/authorized_keys; chmod 640 ~/.ssh/authorized_keys

  • add your keys

 

Configure OpenSSH to only allow bbuser to login (no root)

$ echo -e 'AllowUsers bbuser' | sudo tee -a /etc/ssh/sshd_config

 

(option A) Redirect 8080/8443 to 80/443

$ sudo firewall-cmd --permanent --add-masquerade; sudo firewall-cmd --permanent --add-forward-port=port=80:proto=tcp:toport=8080; sudo firewall-cmd --permanent --add-forward-port=port=443:proto=tcp:toport=8443

 

(option B) Open 8080/8443

$ sudo firewall-cmd --permanent --add-port=8080/tcp; sudo firewall-cmd --permanent --add-port=8443/tcp

 

(optional) Allow postgresql remotely

$ sudo firewall-cmd --permanent --add-service=postgresql

 

(optional) Allow tomcat debugging remotely

$ sudo firewall-cmd --permanent --add-port=2222/tcp

 

(optional) Configure postfix if you need local mail configuration

$ sudo vi /etc/postfix/main.cf; sudo systemctl enable postfix

 

Set max number of open file descriptors

$ echo -e '@bbuser soft nofile 5000\n@bbuser hard nofile 5000' | sudo tee -a /etc/security/limits.conf

 

Overwrite default PGDATA environment variable for postgresql service

$ echo -e '.include /lib/systemd/system/postgresql.service\n[Service]\nEnvironment=PGDATA=/usr/local/bbdata' | sudo tee /etc/systemd/system/postgresql.service

 

Create PGDATA directory and assign ownership to postgres

$ sudo mkdir -p /usr/local/bbdata; sudo chown postgres:postgres /usr/local/bbdata

 

Relabel PGDATA's SELINUX context

$ sudo semanage fcontext -a -s system_u -t postgresql_db_t '/usr/local/bbdata(/.*)?'; sudo restorecon /usr/local/bbdata

 

(if ever needed) Disable SELINUX

  • temporarily:
    • $ sudo setenforce permissive
  • permanently, requires reboot
    • $ sudo sed -i -e 's/SELINUX=enforcing/SELINUX=disabled/' /etc/selinux/config

 

Reboot so that environment, firewall, and other settings take affect

$ sudo reboot

 

Login as bbuser using SSH

 

Initialize postgresql db; enable and start service

$ sudo postgresql-setup initdb; sudo systemctl enable postgresql; sudo systemctl start postgresql

 

Launch into psql as postgres

$ sudo -i -u postgres psql

 

From the postgresql shell paste in:

  • ALTER ROLE postgres WITH ENCRYPTED PASSWORD 'postgres';
  • CREATE ROLE "BBLEARN" WITH LOGIN ENCRYPTED PASSWORD 'postgres';
  • CREATE ROLE "BBLEARN_admin" WITH LOGIN ENCRYPTED PASSWORD 'postgres';
  • CREATE ROLE "BBLEARN_cms" WITH LOGIN ENCRYPTED PASSWORD 'postgres';
  • CREATE ROLE "BBLEARN_cms_doc" WITH LOGIN ENCRYPTED PASSWORD 'postgres';
  • CREATE ROLE "BBLEARN_stats" WITH LOGIN ENCRYPTED PASSWORD 'postgres';
  • CREATE ROLE "BBLEARN_report" WITH LOGIN ENCRYPTED PASSWORD 'password';
  • \q

 

Configure postgresql authentication to require a password instead of using "current user"

$ sudo sed -i -e 's/ ident$/ md5/' -e 's/ peer$/ md5/' $PGDATA/pg_hba.conf; sudo systemctl restart postgresql

 

Add blackboard service to systemd; enable it

$ echo -e '[Unit]\nDescription=blackboard\nAfter=postgresql.service\n\n[Service]\nLimitNOFILE=5000\nType=oneshot\nRemainAfterExit=yes\nExecStart=/usr/local/blackboard/tools/admin/ServiceController.sh services.start\nExecStop=/usr/local/blackboard/tools/admin/ServiceController.sh services.stop\n\n[Install]\nWantedBy=multi-user.target' | sudo tee /etc/systemd/system/blackboard.service; sudo systemctl enable blackboard

 

Create blackboard and bbinstaller directories and assign ownership to bbuser

$ sudo mkdir -p /usr/local/blackboard /usr/local/bbinstaller; sudo chown bbuser:bbuser /usr/local/blackboard /usr/local/bbinstaller

 

Create blackboard license file to server (plain-text in /usr/local/blackboard/config/license/blackboard-license.xml in a working DVM/test environment)

$ vi /usr/local/bbinstaller/blackboard-license.xml

 

Create installer.properties (included below)

$ vi /usr/local/bbinstaller/installer.properties

 

 

Install (and upgrade) Learn

 

Create a checkpoint/snapshot. It should be taken when the system is shutdown for maximum data consistency.

 

Set temporary variable with the new version. For example $ BBVERSION='3500_0_2'

$ BBVERSION='version_tag'

 

Create install directory (can be deleted later to reclaim space)

$ mkdir /usr/local/bbinstaller/$BBVERSION

 

Transfer learn-installer.zip file to server (can be deleted later to reclaim space)

 

Unzip installer.zip to install directory

$ unzip learn-installer-XXXXX.zip -d /usr/local/bbinstaller/$BBVERSION

 

Temporarily change to installer directory and then run the installer

$ pushd /usr/local/bbinstaller/$BBVERSION; ./installer.sh -c /usr/local/bbinstaller/installer.properties; popd

 

Run the PushConfigUpdates admin tool (also tries to fix any permission issues)

$ /usr/local/blackboard/tools/admin/PushConfigUpdates.sh --no-restart

 

Start the blackboard service

$ sudo systemctl restart blackboard

 

 

(optional) Install (and upgrade) Starting Block

 

Install and set AVAILABLE the Starting Block B2

$ /usr/local/blackboard/tools/admin/B2Manager.sh -i /usr/local/blackboard/system/autoinstall/internal.developer/allavailable/starting-block.war; /usr/local/blackboard/tools/admin/B2Manager.sh -s AVAILABLE bb-starting-block

 

Test to make sure it works

 

 

Post Install

 

After installing (and upgrading) review the output in the log files.

  • /usr/local/blackboard/logs/tomcat/stdout-stderr-*.log
  • /usr/local/blackboard/logs/tomcat/bb-access-log.*.txt
  • /usr/local/blackboard/logs/bb-services-log.txt

 

If you see ClassNotFoundException errors for com.blackboard.partners.* the Partner Cloud B2 is missing.

$ /usr/local/blackboard/tools/admin/B2Manager.sh -i /usr/local/blackboard/system/autoinstall/market.pro/allavailable/partner-cloud.war

 

 

(optional) Implement CA-signed Certificate for HTTPS

 

Run the ShowCleartextPasswords admin tool to output the current keystore password

$ /usr/local/blackboard/tools/admin/ShowCleartextPasswords.sh | grep appserver.keystore

 

Set temporary variable with the keystore file

$ BBKEYSTORE='/usr/local/blackboard/config/keystores/tomcat.keystore'

 

Rename current keystore so we have it in case of issues

$ mv $BBKEYSTORE $BBKEYSTORE.bak

 

Generate new private key for certificate

$ keytool -genkeypair -keystore $BBKEYSTORE -storetype jks -alias tomcat -keysize 2048 -keyalg RSA

  • When asked for "first and last name" input the CN of the certificate.

 

Output CSR

$ keytool -certreq -keystore $BBKEYSTORE -alias tomcat

 

Submit CSR to CA. The resulting signed certificate file should be a .p7b.

 

Transfer signedcert.p7b to server (it is plain text)

 

Import signed certificate into keystore

$ keytool -importcert -trustcacerts -keystore $BBKEYSTORE -alias tomcat -file signedcert.p7b

 

Run the PushConfigUpdates admin tool

$ /usr/local/blackboard/tools/admin/PushConfigUpdates.sh --no-restart --fast

 

Restart blackboard service

$ sudo systemctl restart blackboard

 

 

Contents of installer.properties

 

## Hostname and port numbers used when building URLS that get sent ##
##        to browsers or included in notification emails.        ##
##  These should reflect the frontend hostname and ports that are  ##
## used to access the application.                                ##
bbconfig.frontend.fullhostname=localhost.localdomain
bbconfig.frontend.portnumber=443
bbconfig.frontend.protocol=https

 

##  NOTE: this property is read at initial installation only. The  ##
##  value thereafter is set on Admin->System Config->Email Config  ##
bbconfig.admin.email=root@localhost.localdomain

 

## The SMTP host name via which Learn sends email out. This is a mandatory setting. ##
bbconfig.smtpserver.hostname=localhost
## The port on SMTP server port which Learn connects to send email. It will be protocol-default if not specified. ##
bbconfig.smtpserver.port=
##  The boolean flag to indicate whether the SMTP server requires authentication, the value can be either true or false(default)  ##
bbconfig.smtpserver.auth.required=false
bbconfig.smtpserver.username=
bbconfig.smtpserver.password=
## Connection type specifies the way how the emails be encrypted, the valid options are ##
## Default:  the emails are not encrypted.                                              ##
## StartTLS: the emails are encrypted via TLS                                          ##
## SSL:      The emails are emails via SSL                                              ##
## Any other value (including null) will be token as Default.                          ##
bbconfig.smtpserver.connectiontype=default

 

##                  tomcat developer properties                    ##
bbconfig.tomcat.debug.enable=true

 

# default passwords inside Learn, modify as desired #

 

antargs.default.users.integration.password=password
antargs.default.users.administrator.password=password
antargs.default.users.guest.password=password

 


# default postgresql passwords, as pre-configured #

 

antargs.default.vi.db.password=postgres
antargs.default.vi.stats.db.password=postgres
antargs.default.vi.report.user.password=password
bbconfig.database.admin.password=postgres
bbconfig.cs.db.cms-user.pass=postgres
bbconfig.database.server.systemuserpassword=postgres

 

## Enable caching of plugins to local file systems for performance ##
# true - Mimics B2 behavior of Learn SaaS
bbconfig.plugins.cache.enabled=true

 


# typical defaults, do not need editing #

 

bbconfig.appserver.fullhostname=localhost.localdomain

 

bbconfig.basedir=/usr/local/blackboard
bbconfig.file.license=/usr/local/bbinstaller/blackboard-license.xml
bbconfig.java.home=/usr/java/latest

 

bbconfig.database.datadir=/usr/local/bbdata
bbconfig.database.type=pgsql
bbconfig.database.server.instancename=
bbconfig.database.server.fullhostname=localhost

 

bbconfig.database.server.instancenametype.oracle=SID
bbconfig.oracle.client.drivertype=thin
bbconfig.database.indexdir.oracle=/usr/local/bbdata

 

bbconfig.unix.max.open.files=5000

 

bbconfig.inst.name=Blackboard, Inc.
bbconfig.inst.city=Washington
bbconfig.inst.state=DC
bbconfig.inst.zip=20001
bbconfig.inst.country=USA
bbconfig.inst.type=Developer

 

##      java virtual machine config - java bound processes        ##
bbconfig.min.heapsize.tomcat=2048m
bbconfig.max.heapsize.tomcat=2048m
bbconfig.max.stacksize.tomcat=1M

 

bbconfig.jvm.options.extra.tomcat=-XX:+UseCompressedOops -XX:+DoEscapeAnalysis -Xverify:none

 

bbinstaller.skip.db.comments=true

 

# end of installer.properties

 

 

Feb 11, 2019 - added Starting Block installation

Mar 12, 2019 - updated Starting Block installation and added Post Install section