How to install the software?

Published

February 8, 2025

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
jupiter-lab &

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

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
python3 -m pytest --cov=src 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.