Skip to content

Bundling qbank

Jump to bottom
cjshawMIT edited this page Jul 7, 2017 · 9 revisions

Scenarios for bundling

If you need a standalone qbank executable (for running with unplatform, for example), then you can use pyinstaller to create a bundle. This should work with OS X, Windows, or Linux, whatever pyinstaller supports. Note that to create a bundle for a platform, you need to run pyinstaller on that specific platform. You cannot build Windows bundles on OS X.

The bundled package will run on port 8080 unless you manually change main.py and insert the port before bundling, like:

if (not is_test()) and __name__ == "__main__":
    sys.argv.append('9123')
    app.run()

This is because pyinstaller does not allow you to include command line arguments as part of the bundling process.

Windows requirements

To bundle a Windows executable, for use with unplatform, you need to install the following software on a Windows machine or VM (32bit if the field machines are 32bit):

  • 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.
  • 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.
  • Virtualenv: pip install virtualenv
    • Depends on Python. Install that first.
  • Virtualenv wrapper.
    • Depends on virtualenv. Install that first.
  • lxml.
    • Depends on python, virtualenv, and virtualenvwrapper. Install those first.
    • You should do this inside of your virtual environment (see below for instructions on how to set that up and activate it).
    • You most likely need the cp27 and cp27m 32-bit versions, i.e. lxml‑3.7.3‑cp27‑cp27m‑win32.whl.
    • Download the above wheel, and run pip install lxml‑3.7.3‑cp27‑cp27m‑win32.whl. More detailed discussion around this is here.

TL;DR version

Initial build

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

  1. mkvirtualenv qbank
  2. git clone https://github.com/CLIxIndia-Dev/qbank-lite.git
  3. cd qbank-lite
  4. pip install -r requirements.txt
  5. pyinstaller main.spec

Subsequent builds

In a command prompt window:

  1. cd qbank-lite
  2. workon qbank
  3. git pull
  4. pip install -r requirements.txt
  5. pyinstaller main.spec

Rename the final executable

The final executable is now located in dist\main.exe. You can rename this to match the qbank version, i.e. move dist\main.exe qbank-lite-v3.14.9-32bit-ssl.exe.

More detailed instructions are below.

Clone the qbank repository

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

git clone https://github.com/CLIxIndia-Dev/qbank-lite.git

Installing qbank 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 qbank

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

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

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

To learn more about virtual environments, you can read more at 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 qbank-demo

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

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

Pyinstaller

There are many hidden imports in qbank that need to be declared for pyinstaller to include them. The best way to create the bundle is using the included spec file.

pyinstaller main.spec

Updating for unplatform

Once qbank is bundled for unplatform, it needs to get included in the unplatform bundle. This is done by adding the qbank executable to the qbank bundles repository.

  1. Clone / pull that repository.
  2. Add a directory with the qbank version.
  3. Copy in the qbank executable to the new directory, renaming the file to qbank-lite-v#.#.#-32bit-ssl.exe.
  4. Commit and push those changes to master.
  5. Checkout release branch.
  6. Copy the qbank executable into the release/ directory, renaming the file to qbank-lite-v#.#.#-32bit-ssl.exe.
  7. Remove the old exe file.
  8. Commit and push those changes to release.

For example:

$ git pull
$ mkdir v3.14.4
$ cp ~/projects/qbank-lite/dist/main.exe v3.14.4/qbank-lite-v3.14.4-32bit-ssl.exe
$ git add .
$ git commit -m 'with qbank 3.14.4 bundle for windows'
$ git push
$ git checkout release
$ cp ~/projects/qbank-lite/dist/main.exe release/qbank-lite-v3.14.4-32bit-ssl.exe
$ git rm release/qbank-lite-v3.7.7-32bit-ssl.exe
$ git add .
$ git commit -m 'update released windows version'
$ git push
Clone this wiki locally