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:
- The license file from a pre-existing install of the DVM
- /usr/local/blackboard/config/license/blackboard-license.xml - Developer Virtual Machine - DVM
- CentOS 7 x64 (Minimal) iso
- CentOS-7-x86_64-Minimal-XXXX.iso - https://www.centos.org/download/
- Oracle JDK 8 (Linux x64 rpm)
- jdk-8uXXXXX-linux-x64.rpm - https://www.oracle.com/technetwork/java/javase/downloads/index.html
- Learn Installer zip
- learn-installer-XXXXX.zip - from Behind the Blackboard
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)
- You can copy the link from the Oracle Downloads page then:
- $
wget --header 'Cookie: oraclelicense=accept-securebackup-cookie' https://download.oracle.com/otn-pub/java/jdk/.../jdk-8uXXXXX-linux-x64.rpm
- $
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
Blackboard periodically releases an updated Starting Block in their repository.
Upload closest Starting Block war to server - can be older, but not newer
Test to make sure it works
Troubleshoot using the output in /usr/local/blackboard/logs/bb-services-log.txt
- The 3300/3400 blocks require httpclient-4.5.2
- $
wget http://central.maven.org/maven2/org/apache/httpcomponents/httpclient/4.5.2/httpclient-4.5.2.jar -P /usr/local/blackboard/libs/
(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