How to install the software?

Published

April 23, 2026

Prerequisites

Tool Version Notes
Python 3.12+ Required
Node.js / npm LTS Required
git any Required
Rust / cargo latest Optional, for the Rust scoring extension
maturin latest Optional, pip install maturin

How to use the software?

Linux or Mac user

First install a few packages:

apt install imagemagick npm

On a Mac you can replace all apt calls by brew.

Using python3, ipython and Jupyter-Lab

pip install -r requirements.txt

pip may also be pip3 depending on your system.

export PYTHONPATH=src:src/website
jupyter-lab &

Your browser will open, go to experiments directory and click on spinorama.ipynb and play around.

Windows (PowerShell)

Install Python 3.12, Node.js and git manually, then run:

.\scripts\setup.ps1

The script automatically sets the PYTHONUTF8=1 environment variable so that Python reads files as UTF-8 by default (required on Windows).

How to develop the software?

You are very welcome to submit pull requests. Note that the license is GPLv3.

Start with launching the setup script: (maybe as root if you need to install some packages)

./scripts/setup.sh

If it doesn’t work out of the box which is likely, please go step by step:

pip install -r requirements.txt
pip install -r requirements-test.txt
pip install -r requirements-dev.txt

For linting the python, html and javascript code or generating helpers:

npm install .

Please add tests and run them. For Python files:

export PYTHONPATH=src
LC_ALL=en_US.UTF-8 pytest tests

and for javascript files:

npx vitest

Before committing, please check that the various checks are fine:

  1. ./scripts/check_html.sh : check that HTML generated files are conforming.
  2. ./scripts/check_meta.py : check that the metadata file looks sane.
  3. ruff format . will take care of formatting all the python files.
  4. ruff check src tests also need to pass.
  5. prettier -w src/website/*.js will format the javascript files.

Most of the checks are enforced in the pre-submit which means that you cannot commit new codes without passing tests and checks.

Docker

Build and run the project using Docker. The setup mirrors scripts/setup.sh inside the images (Python venv, Node dependencies, third-party assets, Cython and Rust builds).

Build images

  1. Build the base image (installs system packages, Node 22.x, and a recent Rust toolchain):
docker build -f Dockerfile.base -t spin-base:latest .
  1. Build the application image (installs Python/Node deps, compiles Cython/Rust, prefetches 3rd-party assets):
docker build -f Dockerfile -t spinorama:latest .

Run tests (default CMD)

The application image is configured to run Python unit tests and Vitest by default:

docker run --rm -it spinorama:latest

Interactive development shell

Start a shell inside the container, mount your working directory, and expose common ports:

docker run --rm -it \
  -p 5173:5173 \
  -v "$(pwd)":/work \
  spinorama:latest bash

Inside the container:

  • Python venv is already on PATH. Run tests:
pytest -q tests
  • Start the website dev server (Vite) and access it at http://localhost:5173/:
npx vite --host 0.0.0.0 --port 5173
  • Build/update third-party assets (already done at image build time):
sh update_3rdparties.sh
  • Build site assets (or use the existing scripts in package.json):
python generate_html.py --dev --sitedev=http://localhost:8888 --skip-speakers
# or
npm run build

Notes

  • The first build may take a while (downloads Node 22.x and Rust toolchain, compiles dependencies).
  • If you change Python/Node dependencies, rebuild the application image.
  • The base image (spin-base:latest) is shared by the main Dockerfile to speed up rebuilds.