Skip to content

Creating a Basic Bundle

Jump to bottom
cjshawMIT edited this page Mar 29, 2018 · 2 revisions

The basic bundle automates many required steps in the unplatform build process, and is the starting point for creating your own final, customized unplatform distribution. It pulls in all of the necessary software components, initializes the web sessions database, and also provides some useful platform-specific scripts. In short, it automates many of the in-the-weeds tasks and codifies knowledge about the unplatform components.

Script for basic bundle

This script is located at scripts/build_scripts/build_script_all_ssl.sh. There is one script for Windows / Linux / OS X, but it has to be run on the final target platform. i.e. to build for Windows, you run the script on a Windows machine.

Before you build, you need to do the following:

  1. Install the build platform dependencies
  2. Set up GitHub SSH keys
  3. Clone the unplatform repository
  4. Install unplatform dependencies
  5. Run the unplatform build script

The instructions for these steps are below.

Tools included in build

The build script fetches and builds all of the tools and sub-packages that are required for unplatform to work. This includes:

  1. qbank.
  2. Content player.
  3. Open assessments player.
  4. Police Quad.
  5. Biomechanic.
  6. Physics video player.
  7. Open story tool.
  8. Turtle blocks.
  9. StarLogoNova simulations.
  10. Rotation of Earth Animation.
  11. Motions of the Moon.
  12. Planet Trek.
  13. Element Hunt.
  14. Solar System Animation.
  15. Moon Track.
  16. Ratio Patterns.
  17. Ice Cubes in Lemonade.
  18. Food Sharing.

Installing build platform dependencies

The build scripts assume that certain software is installed on your build system. Many of these packages come pre-installed on OS X and Linux, but may not be. Some packages are Windows-specific and can be ignored for other platforms. Because the main target platform is Windows, this section will assume you are setting up a Windows build system.

Required software (Windows)

  • 32bit Windows VM or machine. (64bit is okay if your target platform supports it)
  • OpenSSL for Windows.
    • Be sure to choose the installer that's compatible with your machine and is recommended for software developers. For example: if your virtual machine is running 32-bit Windows, select the 32-bit version of OpenSSL recommended for software developers.
    • You might have to modify your system path to use OpenSSL in the command line. To test this, open Command Prompt and type openssl. If that command throws an exception, add openssl to your path by doing the following:
      • Close Command Prompt.
      • Right click My Computer and select Properties.
      • Click Advanced.
      • Click Environment Variables.
      • Edit Path in System Variables (not User Variables). System Variables modal
      • Click New in the variable window.
      • Type in C:\OpenSSL-Win32\bin, and save that.
      • Save and exit the Properties modal.
      • Open Command Prompt and type openssl and press the return button. If the command path changes to OpenSSL>, you've successfully installed OpenSSL and configured your system path to use OpenSSL.
  • Visual Studio C++ Compiler for Python 2.7.
  • Visual Studio C++ Redistributable.
  • Python 2.7.
    • You might have to modify your system path to use Python in the command line. To test this, open Command Prompt and type python. If that command throws an exception, add python to your path by doing the following:
      • Close Command Prompt.
      • Right click My Computer and select Properties.
      • Click Advanced.
      • Click Environment Variables.
      • Edit Path in System Variables (not User Variables). System Variables modal
      • Click New in the variable window.
      • Type in C:\Python27, and save that.
      • Edit the Path again.
      • Click New again.
      • Type in C:\Python27\Scripts, and save that.
      • Save and exit the Properties modal.
      • Open Command Prompt and type python and press the return button. If the command path changes to >>>, you've successfully installed Python and configured your system path to use Python.
  • Git for Windows.
  • Node.js.
  • Yarn.
    • Depends on node.js. Install that first.
  • GNU zip for Windows. Note that this is a command-line only tool, once it is installed.
  • Virtualenv: pip install virtualenv
    • Depends on Python. Install that first.
  • Virtualenv wrapper.
    • Depends on virtualenv. Install that first.

Required Software (Ubuntu)

Make sure that you apt-get install the following packages:

  • lib32z1-dev
  • libxslt1-dev
  • python-dev
  • zlib1g-dev
  • libssl-dev
  • libxml2-dev
  • libffi-dev

Making sure you have GitHub set up locally

Since the GitHub tool repositories are currently private, you will need to have SSH keys set up on your GitHub account, on the build machine. Please follow the Github instructions on how to do that.

TL;DR version

Initial build

(once you have all the dependencies installed) In a command prompt window:

  1. mkvirtualenv unplatform-v2
  2. git clone https://github.com/CLIxIndia-Dev/unplatform_v2.git
  3. cd unplatform_v2
  4. pip install -r requirements.txt
  5. cd scripts\build_scripts
  6. build_script_all_ssl.sh

Then, add modules and data manually into the generated bundle. Read this documentation.

Subsequent builds

In a command prompt window:

  1. cd unplatform_v2
  2. workon unplatform-v2
  3. git pull
  4. pip install -r requirements.txt
  5. cd scripts\build_scripts
  6. build_script_all_ssl.sh

Then, add modules and data manually into the generated bundle. Read this documentation.

More detailed instructions are below.

Clone the unplatform repository

In Git bash or Command Prompt, clone the unplatform repository into a project directory:

git clone https://github.com/CLIxIndia-Dev/unplatform_v2.git

Installing unplatform dependencies

Once you have the above software installed, you need to install the python dependencies (preferably into a virtual environment) using the command prompt or git bash:

Setting up a virtual environment

In Git bash or Command Prompt, create a virtual environment:

mkvirtualenv unplatform

This will automatically create and then activate the virtual environment. Your prompt should show the name of the environment, like:

C:\Users\you> mkvirtualenv unplatform-demo
New python executable in C:\Users\you\Envs\unplatform-demo\Scripts\python.exe
Installing setuptools, pip, wheel...done.

(unplatform-demo) C:\Users\you>

To learn more about virtual environments, you can read more on python-guide.org.

Activiting an existing virtual environment

If you've already done the above steps and want to activate / use an existing virtual environment, at the command line you can type:

workon unplatform-demo

Your prompt should change to reflect the active environment. Now you can continue building unplatform.

Installing dependencies into your virtual environment

Once you have a virtual environment, you can run this to install / update the project dependencies. You should run this every time you pull from the repository with updated code:

pip install -r requirements.txt

Running the build script

NOTE: for transfer size reasons, ideally you have no ePubs in your modules/ directory when running the build script, otherwise they will get included in the zip file and potentially create a 1GB+ file.

You need to bundle on the target deployment platform. For example, to get a Windows bundle, you run build_script_all_ssl.sh on Windows. After cloning / updating the repository and dependencies:

git pull
cd scripts\build_scripts
build_script_all_ssl.sh

If you set a password on your GitHub SSH private key file, then you will be prompted to enter that password for each of the tool repositories. Note that you only get one chance, and if you type in the wrong password, the script will fail silently -- it will continue building, but the final bundle will be missing that tool.

After the bundling is done (~10 minutes for a first-time build), the final zip file appears in bundle\unplatform_vX.X.X_win32_ssl.zip.

node-sass errors

Sometimes when building the OEA player, you'll run into an explicit node-sass error (seen on Windows), or you'll get the final player with no CSS files (seen on Ubuntu). In this case, the node-sass binary wasn't updated or installed correctly, so you'll need to rebuild it.

cd tool-repos/OpenAssessmentsClient/client
npm rebuild node-sass

Then re-run the build script.

Next steps

Now that you have a bundled version of unplatform, you will need to add in the CLIx modules and assessment data. To do so, follow the documentation on the field installation and data files wiki page.

Updating the qbank executable

Because the build scripts automatically fetch the latest qbank bundle from this qbank-lite github repo, in order to update the qbank version included with unplatform, you need to bundle qbank separately and push the bundle to that repository.

Follow the instructions in the qbank wiki to do that.

Clone this wiki locally