2. Installation

2.1. Installing on Windows 10/11

  1. Download the official Windows installer for the L’ART Research Client on Windows.

    You can find the latest release (as well as earlier versions) at github.com/lart-bangor/research-client/releases.

  2. Once downloaded to your device, open the Downloads dialogue in the browser and click Open file. Alternatively, navigate to your Downloads folder in File Explorer and double click on the installer file.

    Screenshot of Windows download dialogue showing the downloaded installer file.

    Fig. 2.1 Open file from downloads

    Note

    If you have Microsoft Defender active, you may be warned about running an unrecognised app.

    This is expected behaviour for unsigned software downloaded from the internet. It is meant to get you to check that you’ve downnloaded the Software from a reputable source before running it.

    This is fine if you’ve used our official download link above!

    Click Run anyway to continue with the installation.

    An image of protection message from Windows taken from Microsoft Defender Smartscreen.

    Fig. 2.2 Microsoft Defender SmartScreen

  3. Select you preferred install mode.

    We recommend choosing Install for me only for most use cases, which will install the app only for the current user.

    However, you may wish to install the app for all users. For example, if you’re installing on a shared university or lab computer and want to centrally manage the installation for all users (requires administrator privileges).

    If in any doubt, choose Install for me only.

    Screenshot of selecting an install mode for users

    Fig. 2.3 Install mode setup

  4. Click Yes to allow L’ART Research Client to make changes to your device (namely, to install the app).

    Screenshot of User Account Control Screen.

    Fig. 2.4 User account control screen

  5. Read and accept the licence agreement.

    You must accept the agreement before installation can begin.

    Screenshot of setup screen for the License agreement.

    Fig. 2.5 License agreement

  6. Select the destination location for your app.

    Normally you should be able to leave this at the path already suggested by the installer, which will be the default directory for app installation for your system and the chosen installation mode.

    Make sure you have at least 65MB of free disk space on your device.

    Click Browse… if you wish to change the installation path of the app.

    Screenshot of setup screen requesting the user to select a destination location

    Fig. 2.6 Select destination location

  7. Click Install to install the L’ART Research Client app on your device.

    Screenshot of application ready for installation.

    Fig. 2.7 Install Research Client app

  8. Complete setup by clicking Finish and enjoy!

    Screenshot of completing the L'ART Research Client Setup Wizard

    Fig. 2.8 Complete setup of Research Client app

2.2. Installing on Linux

This currently requires building from source or running as a Python package (requires Python 3.10), but should run if you have Chrome or Chromium installed.

Note

Help wanted!

We would welcome help for developing a sustainable workflow to build distributables for Linux. If you have any experience with packaging for one or more Linux distributions (e.g. as flatpaks, *.debs, snaps, etc.) and would be willing to help with that please do get in touch!

2.2.1. Running as a Python package

The easiest way is to run directly from source. On Ubuntu 22.04, follow the steps below the get the source code and all the dependencies installed. The last line will run the Research Client.

sudo apt install chromium-browser python3-pip python3-tk -y
python3.10 -m pip install pipenv
cd ~/
wget https://github.com/lart-bangor/research-client/archive/refs/tags/v0.4.1.tar.gz
tar -xf ./v0.4.1.tar.gz
rm ./v0.4.1.tar.gz
cd research-client-0.4.1
python3.10 -m pipenv install
python3.10 -m pipenv run python ./manage.py run

If you want to make an executable shortcut, create a file with the executable flag (+x) in your ~/.local/bin directory. You can do this by following these steps:

$ cd ~/.local/bin
$ echo > research-client
$ chmod +x research-client
$ gedit research-client

In the editor that pops up, enter the following text and then save the file:

#!/usr/bin/env bash

cd ~/research-client-0.4.1
python3.10 -m pipenv run python manage.py

After saving the above, you can now launch the Research Client from the terminal by just typing in research-client and hitting Enter. (You may need to log out and log back in if this doesn’t work straight away…)

2.2.2. Building from source

Alternatively, if you want to build the app properly for your system, you can follow the steps for Setting up the development environment from the Developer Guide, and then just run python3.10 -m pipenv run python manage.py build from inside the project’s root directory.

This will produce a tarball (*.tar.gz) in the ./dist/linux/ directory containing the full set of binaries for the application, which can then be installed in the appropriate way for you system or run directly from the executable therein.

The only real advantage this might offer is if you want to install the Research Client on several machines, as you can just copy over the tarball, exctract it and run the app, without needing to worry about any dependencies (they are all packaged together when the executable is built). There is no real additional advantage over running as a Python package.

2.3. Installing on MacOS

This currently requires building from source or running as a Python package (requires Python 3.10), but should run if you have Chrome or Chromium installed.

Caution

App termination issue on MacOS

There is currently an issue where the app may not terminate correctly on MacOS after the main window has been closed. If the background Terminal window remains open after a few seconds, this may have to be closed manually and the user may have to confirm that they want to really terminate the process.

This is not harmful beyond the annoyance value, as long as the user does not close the Terminal window before they have finished the data collection.

For more information see #37.

To build from source follow the same instructions as for Linux above, with some adjustments necessary (such as using port instead of apt). Since we don’t currently have full instructions that have been tested on MacOS for this, it will be preferable to run as a Python package unless you want to actively figure out any problems you might encounter during the build.

To run as a Python package, follow these instructions:

  1. Install Chrome from the app store (or install Chromium using your preferred method).

  2. Install the latest version of Python 3.10x (that is version 3.10.10 as of the time of writing not 3.11.x!) from the official Python releases for MacOS.

    After runnin the installer, open a Terminal and check that python3 --version prints something like “Python 3.10.10”. This means python has installed correctly and you’re ready to continue.

  3. Install pipenv with the command pip3 install pipenv. This should print out a success message at the end of the process. You can ignore any messages it might print about updating pip itself (or follow the instructions it provides if you like).

  4. Now run the following commands in your terminal to set up the package from source:

    cd ~
    curl -L https://github.com/lart-bangor/research-client/archive/refs/tags/v0.4.1.tar.gz -o research-client.tar.gz
    tar -xf ./research-client.tar.gz
    rm research-client.tar.gz
    mv research-client-0.4.1 research-client
    cd research-client
    python3 -m pipenv install
  5. You can now launch the app from within a terminal, provided you are in the directory ~/research-client, using the following command:

    python3 -m pipenv run python3 ./manage.py run
    

Obviously, you will not want to open a Terminal, do cd ~/research/client and then type python3 -m pipenv run python3 ./manage.py run every time. You can create a shortcut which can be clicked to launch the app by following these additional steps:

  1. Make an executable .command file inside the ~/research-client directory by running the following in a Terminal:

    cd ~/research-client
    echo > research-client.command
    chmod +x ./research-client.command
    open -a TextEdit ./research-client.command
    
  2. In the editor that popped up with the last command above, copy and paste the following code, then save and close the file.

    #!/usr/bin/env bash
    
    cd ~/research-client
    python3 -m pipenv run python3 ./manage.py run
    
  3. Once you’ve created the research-client.command file as per the two steps above, you can just locate it in Finder (e.g. launch Finder, then in the top click on Go -> Home, and open the research-client folder) and then drag and drop the research-client.command onto your dock.

    When you click on the file in the dock now, it should launch a Terminal window together with the app.