Developing

Introduction

This page describes the tools needed to develop on the Genisys project. The Genisys project currently targets Ubuntu 22.04, but the project strictly uses the interpreted programming languages of Python 3, NodeJS, and Bash, so it can be developed anywhere those run.

Setting Up Your Environment

Python

The current version of Python supported by the Ubuntu 22.04 LTS release is Python 3.10.12 making this the target and supported version for development. You can refer to the GitHub Actions to determine support for other Python 3 versions.

If you are developing on Windows or MacOS, there is not an official Python 3.10.12 release that you can download. Installing the 3.10.11 release from the official downloads page should suffice. If developing on Linux, it is best to use the version in your distribution's package manager, but you can use Docker or Pyenv if it does not match the Genisys project's target version.

Poetry

Once you have obtained a working copy of the Python interpreter, you can install the Genisys project's Python dependencies. The project uses the modern pyproject.toml format, as described in PEP 621. As such, we use Poetry to manage the project's Python dependencies. As the exact packages and versions are constantly changing, please refer to the pyproject.toml for up-to-date information.

You can install Poetry any number of ways, including pip, pipx, or your distribution's package manager, however the most reliable way is to use a dedicated virtual environment for the Genisys project. Additionally, although Poetry can manage your virtual environment, if you use VSCode your virtual environment needs to be in the project's directory for VSCode's environment detection to work correctly.

The steps below describe setting up the project's virtual environment. The commands assume you are using Bash (or another Bourne-esque shell), if you are on Windows, please use Git Bash as distributed with Git for Windows.

# clone the repository
git clone https://github.com/xeluior/genisys.git
cd genisys

# setup the virtual environment
# ensure you are using the correct python version as described above
python -m venv .venv

# activate the virtual environment
source .venv/bin/activate

# install poetry
pip install poetry

# install the project dependencies
poetry install

NodeJS

For the web frontend, the Genisys project utilizes the MeteorJS framework. The current version of MeteorJS, version 2.15, run on a relatively old version of NodeJS: version 14. Officially, Meteor supports Node ">= 10 and <= 14", but we advise using the latest version available for security purposes.

The official NodeJS website still hosts installers for NodeJS version 14.21.3 for MacOS and Windows on it's download page. Alternatively, you can install nvm which has the added benefits on Linux of not requiring root to use the -g flag with npm install. Please follow the instructions for installing nvm from it's README, then use the following commands in install and activate Node 14 for the project.

nvm install 14
nvm use 14

Meteor JS

Once you've installed the requisite version of NodeJS, installing meteor is a relatively straightforward process. You can follow the instructions from the Meteor Documentation or simply run npm install -g meteor (make sure you are running Node 14 per the last section). Once that command has completed, change to the "meteor-dev" directory, which includes the project's package.json and run meteor npm install to get the project's other JavaScript dependencies.

Building

Building the Genisys project for deployment is currently a two step process. The Meteor JS frontend is first built into a Tarball using the command meteor build ../genisys/server/external, ran from the "meteor-dev" directory. This generates the "meteor-dev.tar.gz" file in the Python package path. Next poetry build is ran from the project root. This creates the "dist" folder with two files, "genisys-${version}.tar.gz" and "genisys-${version}-py3-none-any.whl", where "${version}" corresponds to the "tool.poetry.version" field of the pyproject.toml.

At this point, the dist files can be pushed to PyPI with poetry publish, but there is currently a name conflict with an existing package named genisys on the office Python Package Index. Pending a rebrand, the package can only be published to a private package index or manually copied and installed to the target machine with Pip on that machine. See the runtime dependencies article for more information on deployment.

Finishing Up

At this point you are ready to begin developing on all aspects of the Genisys project. Be careful when testing functionality though. As Genisys sets up several dependent system services (and often needs to do so as root), it is best to run tests in a VM. A VirtualBox VM image with only the runtime dependencies installed is available by running the test script. If you can't use the prebuilt image, or are looking to deploy to real hardware, please refer to the article on runtime dependencies for more information.