Developer Virtual Machine

Version 24

    Blackboard now provides a preconfigured VirtualBox virtual machine to help developers quickly test and validate your Building Blocks. This article will help with setting up your developer environment to use the VM.


    Important Note: You are downloading a Blackboard Learn Developer Virtual Machine instance (the “Bb Virtual Machine”) containing the Blackboard Learn developer software. The Bb Virtual Machine shall be deemed a part of the Blackboard Developer Software provided to you pursuant to the terms of your developer license agreement with Blackboard. All terms and conditions of your developer license agreement to the Blackboard Learn software shall remain in full force and effect and shall apply in all respects to the Bb Virtual Machine and your use thereof. The Bb Virtual Machine and the Blackboard Learn developer software contained therein are provided “as is”. Except as expressly stated in your developer license agreement, Blackboard disclaims all warranties and liability associated with the Bb Virtual Machine and your use thereof. By downloading or accessing the Bb Virtual Machine, you re-affirm your agreement to the terms of your developer license agreement for the Blackboard Learn software and further agree that your use of the Bb Virtual Machine shall be subject to the terms and conditions of your developer license agreement. If you do not agree to the foregoing terms, you may not download or use the Bb Virtual Machine.



    • Developer-class workstation or laptop that supports Linux virtual machines.
    • VirtualBox
    • Vagrant




        1. Create a directory on your computer for your Vagrant VM. For example: $HOME/Vagrant/Learn
        2. Download the Vagrant virtual machine and Vagrantfile from Behind the Blackboard and place them in the directory listed in Step 1. If you are a developer and need access to Behind the Blackboard, read Become a Blackboard Partner and Gain Access To Behind the Blackboard and Partner SaaS Systems.
          Note: If downloading the April 2014 release, make sure to download both the virtual machine and the Vagrant file into the same directory.
        3. For the April 2014 release, rename the downloaded vagrantfile to Vagrantfile.
        4. For releases other than April 2014, unzip the archive file to extract the .box file and Vagrantfile. If the archive file does not include a Vagrantfile, run vagrant init FILENAME to initialize the .box file and create Vagrantfile.
        5. Run the following commands in that directory:
          vagrant up
          vagrant ssh

          If you are on a Windows host machine, you may experience issues logging into the VM because of Windows' management of SSH. Alternatively, you can log into the VM using any SSH client you want by connecting to localhost:2222 and using the credentials vagrant/vagrant. Additionally, help is available on the Vagrant site.

        6. You are now logged into the VM.  Run the following command to start Learn:
          sudo /usr/local/blackboard/tools/admin/ services.start


    Using the Virtual Machine


    You can now access your developer instance of Learn at http://localhost:9876 or https://localhost:9877 The Learn administrator login credentials are administrator/password.


    Developer License


    This virtual machine is pre-licensed with a developers license, and is not intended to be re-licensed with your institution's license or personal developer license. Because a Developer license is in use, there are certain limitations:

    • 150 Users
    • 100 Courses
    • 1000 Enrollments


    Starting Block


    This Building Block allows you to deploy your Building Block remotely, and is already installed and configured on the Q4 2015 machine. To install on the October or April release, you can download the latest here. Use of the Starting Block on the April and October releases will require adding a line to the Vagrantfile, a configuration change in the file of the running instance, and an update to your build.gradle file.


    Vagrant File Edit



  :forwarded_port, guest: 8080, host: 9876



    Set the frontend.protocol to http in






    Change the build.gradle deployServer to connect on localhost:9876:


    deployServer = "localhost:9876"


    Attaching to the Tomcat Debugger


    The tomcat debugger may be attached via port 9878.


    Accessing the Virtual Machine Users


    The user which is by default logged onto the virtual machine is named vagrant and has the password of vagrant.


    After you have ssh'd to the virtual machine you have the need to perform root privileged operations:

    vagrant ssh
    su - root #the root password for the virtual machine is vagrant


    Accessing the Database Directly


    To access the database directly (for running SQL), you must be logged in as the postgres user:

    vagrant ssh
    sudo su - postgres
    psql BBLEARN


    The user and password for accessing the database when not logged in as the postgres user is postgres/postgres.


    As of the Q4 2015 release, port 5432 is forwarded to your host machine at 9879, so you can set up a "remote" connection using pgadminIII or your preferred database tool.


    Additional Changes in the Q4 2015 Virtual Machine


    In addition to pre-installing the starting block, pre-configuring the machine to use http by default, and forwarding the postgresql port with appropriate access permissions, the tomcat wrapper timeout value has been set to 0 to avoid the timing out of the Java Debugger. The memory allocation is initially set to 4gb in the Vagrantfile, as well. Simply modify the entry in Vagrantfile to adjust this value.


    There is also a zip file containing an OVA file. OVA is a Open Virtual Appliance that can be imported into any virtual host that can support the format. The virtual appliance is built with the same settings as in the Vagrantfile, but in order to change the settings, you will need to consult the documentation for your virtual host provider.


    To share comments and feedback on the developer virtual machine, please email developers (at) blackboard (dot) com.