You are here: Home >

     Search  Print Send to a friend
  Home   About ELM   Contribute    Subscribe to Newsletter  Contact us    

Featured Articles

How To Create A Blackboard Test Environment

Spring is in the air. The sun is shining and your blackboard production environment hums along peacefully.

Developers have been toiling all winter, and Blackboard cheerfully announces that the fruits of their labour are ready to be picked and oh, by the way, you should prepare for Oracle9.

Their enthusiasm is catching. Your project manager is looking forward to the new features she'll be able to offer your users, and frankly, you wouldn't mind seeing some of those annoying bugs vanish in the process.

So you set the date for the update.

And the nagging at the back of your brain begins.

You've been lurking on the mailing lists, and frankly, some of the stories you've read there sound horrific.

As far as you can see, you have three of options: 1) hold your breath and pray the update will run without a glitch, 2) have Global Services update your systems, or 3) dig out those test servers, copy your current production environment, and run the updates until you have documented everything down to the last detail.

Most people sleep better when they know what to expect.

And at least setting up your test environment should be painless. Here's how.


The "Blackboard Academic Suite Hardware Sizing Guide" ( lists the hardware recommendations for production servers.

If you cannot afford similar hardware for your test environment, look around for anything powerful enough to run your operating system and your database. Our first test server was a spare PC with a 900MHz CPU, 512 MB RAM, and 30 GB disk space. Not my first choice to test a full scale migration, but adequate to test a software update.

Network Configuration

While accidentally overwriting your production data from your test environment is a quick and reliable way to learn the ins and outs of database backup/restores, for your users sake, you should look for alternative training opportunities.

If your test environment is on the same network as your production environment, an easy way to avoid contamination is to assign unused ip addresses to the names of your production servers in /etc/hosts or %SystemRoot%\system32\drivers\etc\hosts.

On linux, verify that /etc/nsswitch defines the hosts file before any other databases. On windows run "ipconfig /flushdns" to reload the new values in the dns cache.

For convenience sake, you can add your production servers to /etc/hosts using different host names.


So how do you get a copy of your Oracle production database in your test environment?


If your test environment runs the same operating system and database software version as your production environment, the easiest and fastest way to reproduce the production database is to simply copy it. There are several good descriptions of how to do this on the internet. is one example, which incidentally also shows how to rename the database in the process. Renaming your test database is another safety precaution against accidentally overwriting your production environment.

One thing these websites often forget to mention is that you also need to add the new database to standard oracle files such as /etc/oratab, $ORACLE_HOME/network/admin/listener.ora and $ORACLE_HOME/network/admin/tnsnames.ora. And that it does help to (re)start the listener.


If your test database server runs another operating system, or if you're considering moving your database from Oracle 8.1.7 to Oracle or higher, a database export/import seems more appropriate. But there are a few snares to watch out for.

Sequence Numbers

The bb_bb60 schema of the blackboard database contains a lot of triggers, many of which are used to create values for pk1 columns based on sequence numbers. If you export the database while it is being used, chances are that you'll end up with inconsistencies, despite using the "consistency=y" qualifier. You may see these during the index rebuild at the end of an import operation, or as constraint violations at runtime. You can get past them, usually by increasing the sequence number to the corresponding max( pk1 ) + 1, but if have the option to interrupt production for a while, stop your database listener(s), shutdown your database, restart it, and then run the bb_bb60 export.

We'd be down for less than 15 minutes. If you want an estimate of what it would take in your environment, time the export while the database is up and running.

Oh. Don't forget to restart the listener(s) and blackboard when you're done.

Character Sets

The export utility automatically exports user data in the character set of the export server, and the import utility converts it just as automatically to the character set of the import server.

If you notice that accented characters have lost their accents, you probably forgot to define the environment variable NLS_LANG. For blackboard version 6, define:


and observe the result in the description heading of the export/import output log.

Elapse Time

Depending on how big your database is, importing can take a considerable amount of time.

With a little under 30M records in the activity_accumulator table, our last import took well over 16 hours. Most of that time went to rebuilding the database indexes, the I/O subsystem being the limiting factor.


If you remembered to set the NLS_LANG variable, the export won't pose a problem.

Replace BB6DB with the ORACLE_SID of your production database, verify that your working directory has enough free diskspace, and run this from the oracle account:

$ exp \"sys@BB6DB as sysdba\"

owner=(bbadmin, bb_bb60, bb_bb60_stats)


file=bb6-`date +%Y%m%d`.dmp \

log=bb6-`date +%Y%m%d`.dmp.explog

create new database

While you wait for the previous command to finish, you can create a new Oracle 9i database. The dbca utility will make it painless.

All that remains to be done prior to importing the data is creating the tablespaces, defining the user accounts, and granting them all the required roles and privileges.

The script on can help you do just that.

When run against a blackboard production database, it will create another script, named
bb-init-db.sql, which contains all the necessary commands.

Simply log into the oracle installation account on your production database server, copy the script, make it executable (chmod 750, define the environment variable ORACLE_SID as the blackboard database, and execute the script (./

Copy the resulting bb-init-db.sql to the test database server, edit it to change the tablespace locations if so desired, connect to the new blackboard database using a sysdba account and execute bb-init-db.sql.

Your test database is now ready for import.


Assuming the test database name is BB6DBT, the import command looks like this:

$ imp \"sys@BB6DBT as sysdba\" \

commit=y \

full=y \

file=bb6-`date +%Y%m%d`.dmp \


log=bb6-`date +%Y%m%d`.dmp.implog

As noted previously, the import command can take forever to complete. If you suspect it is hung up, monitor the database files for access time and growth. A "watch ls -ltr" of the directory containing the data files should assure you that the import is still running fine.

You did remember to define NLS_LANG, did you?


Once the database copy or the export/import terminates, put your mind at ease, and run a quick verification. On the test application server, add the database to the tnsnames.ora, and check whether you can access it from sqlplus. If you can, the application will be able to as well.

changing the database data

As far as the database is concerned, all that remains is to make it aware of its new environment. Assuming the test application server runs on a host named castor, and the database server runs on pollux, these commands will adjust the links:

# sqlplus bbadmin@BB6TC

SQL> UPDATE bb_config_registry

SET hostname = ''

WHERE pk1 = 1;


SQL> UPDATE bb_instance_host

SET hostname = '';


SQL> UPDATE bb_instance

SET db_host = 'pollux',

db_instance = 'BB6DBT',

stat_db_host = 'pollux';



application server

On linux, setting up the application server quite literally starts with a copy of the production environment. Use your favourite tool to copy all files under /usr/local/blackboard from your production server to your test server. Verify that the copy preserved ownership, permissions, and the one softlink from /usr/local/blackboard/logs/tomcat to

Blackboard stores the names of the database and of the application and database servers in a number of files. If you replace 'altair' by the hostname of your database server, mirfak by the name of your application server, and BB6DB by the name of your production database, these commands will return a list of files containing these strings, along with the number of occurrences:


# cd /usr/local/blackboard

# find . \

-path ./backups -prune -o \

-path ./content/vi/bb_bb60/courses/ -prune -o \

-path ./content/vi/bb_bb60/recyclebin -prune -o \

-path ./docs/vi -prune -o \

-path ./logs -prune -o \

-path ./server -prune -o \

-type f -exec egrep -Hce altair -e mirfak -e BB6DB {} \; | \

grep -v ":0$"


Use your favourite editor and change the names to those of your production environment.

The Proof of The Pudding

With your database up and running, your application copied and reconfigured, all that remains is restarting blackboard.

If your old startup script returns errors, try the one on

Adjust the variables BH, KD, and LD to point to valid directories in your environment, and execute the script with the 'cleanup' option. It will set a number of environment variables for Oracle, cleanup log files, recreate the ones that need to be owned by bbuser with the proper ownership, and start blackboard in your test environment.

You are now set to test Blackboard's latest update.

Unfortunately, you now also no longer have an easy excuse when an instructor asks you to restore a single course because he accidentally wiped the grades...

Author: Herta Van den Eynde

23 June 2005

VLE: Blackboard



| Disclaimer | Copyright | Privacy Policy | Terms of Use | Design by GreenDigit