Skip to main content

Access & Basic Usage

Access and Usage​

Requirements​

  • Minimum: 8 GB RAM, 4 cores, 5-10 GB free disk space, Internet browser (recommended Google Chrome)
  • Recommended: 16 GB RAM, 8+ cores, 15-20+ GB free disk space
  • For viewing and processing H & E images (rakaia v0.23.0 or greater), an installation of vips for the appropriate OS

Additionally, for users installing from source:

  • Python 3.9 or 3.10, or conda (Recommended to use the full Anaconda installer)

Note: rakaia is currently in the beta development stage, and may be subject to breaking changes with each minor and patch release. Please email mwatson@lunenfeld.ca to request access to the rakaia source code, which is required for installation.

rakaia can be installed locally without an environment or container, but this is not recommended for dependency management:

# cd rakaia
pip install -r requirements.txt
pip install .

With conda​

conda is the recommended installation manager for rakaia. To install conda locally, visit this link and select the relevant operating system.

Once conda is installed:

conda create --name rakaia python=3.9
conda activate rakaia
# cd rakaia
pip install -r requirements.txt
pip install .

Updating local installations​

From source, rakaia can be updated locally using the following commands. Note that this method requires access to the source code repository. Please contact mwatson@lunenfeld.ca to request repository acces privileges. 

# navigate to the directory where you cloned rakaia from github
cd rakaia
git switch main
git pull --all
pip install .

Running rakaia​

The ClI options and help screen for running rakaia can be viewed using:

rakaia -h

After installation, rakaia can be run through conda or simply executed using the rakaia command:

conda activate rakaia
rakaia

After a few moments, rakaia should auto open in a new browser window. Otherwise, the user should then navigate to http://127.0.0.1:5000/ or http://0.0.0.0:5000/ to access rakaia.

The current version of rakaia can also be checked on the command line with the following:

rakaia -v

Custom Ports​

Users are able to specify a different port for rakaia web session (the default port remains 5000). Suggested alternative ports are 8050 and 8080. The port can be specified in the CLI with:

rakaia -p 8050

The local URL will then take the form of http://127.0.0.1:{port} such as http://127.0.0.1:8050/

Local file dialog​

Users may also have the option to install and use a local file dialog rendered with wxPython on local runs. This can be instantiated with the -l CLI option when running rakaia (by default, this feature is not included):

rakaia -l

IMPORTANT: Due to the limitations of wxPython on multi-threaded systems as well as compatibility problems on different OS options, this feature is not likely to work properly on macOS.

In order to use this feature, users should make sure to install wxPython from the proper download page

Other options​

By default, rakaia will run in threaded mode. To disable using a multi-threaded application instance, add -dt as a command line option (not recommended):

rakaia -dt

rakaia also uses bootstrap-style load screens to indicate that data are being imported or changed (i.e. on an ROI change). To disable the load screens for data manipulation, use the -dl CLI option:

rakaia -dl

rakaia supports custom default colour swatches that are input by the user. An example using 14 custom colours:

rakaia -sc "#25262b,#868e96,#fa5252,#e64980,#be4bdb,#7950f2,#4c6ef5,#228be6,#15aabf,#12b886,#40c057,#82c91e,#fab005,#fd7e14"

custom color swatches will replace the default color bars used for channel recoloring.

Basic authentication​

NOTE: As of rakaia 0.20.0, basic authentication has been removed. This section only applies to older versions of rakaia.

rakaia uses basic authentication upon a new session. The credentials are as follows:

  • username: rakaia_user
  • password: rakaia-1

Docker​

rakaia can be run using Docker with the following commands (requires an installation of Docker):

cd rakaia
docker build -t rakaia .
# use -d to run detached in the background
docker run -d -p 5000:5000 rakaia:latest rakaia -pr

Local file destinations can be mounted for direct access to local filepaths in the containerized environment, such as :

docker run -p 5000:5000 -v /home/:/home/ rakaia:latest rakaia -pr

Navigate to the local address http://0.0.0.0:5000/ or http://127.0.0.1:5000/

Note: rakaia MUST be run in production mode in a Docker container. For more information, visit the Performance section of the documentation.

Running shared instances​

Docker serves as the entrypoint for running a shared instance of rakaia (i.e. on a remote server to multiple concurrent users). Importantly, the -dc flag MUST BE SET when deploying the shared container; this disables session cache overriding, which permits each individual callback invocation to serve unique data to the user and prevents users from overriding each other's server side callback invocations. This is required for multiple users to access the application simultaneously and potentially invoke callbacks at the same time.

The recommended command to deploy rakaia in production mode a shared/concurrent environment through Docker (detached) is: 

docker run -d -p 5000:5000 rakaia:latest rakaia -pr -dc -da

For developers​

rakaia can be run in editable mode with either configuration shown below, which permits source code changes to be applied to the application on the fly:

pip install -e .
rakaia

Installing an editable version through pip is also required to run unit tests:

pytest --headless --cov rakaia

Conversely, without app installation:

python rakaia/wsgi.py

Developers should note that running the application in the default mode will also for debugging and source code updates. These features are disabled when using production mode with -pr.