SoL 4.0a4

Carrom tournaments management

Version:

4

Author:

Lele Gaifax <[e-mail]>

license:

GPLv3

Status:

This project contains some tools that make it easier the organization of a championship of Carrom tournaments using a variant of the Swiss system, or even everyone against everyone events.

The main component is a Pyramid application serving two distinct user interfaces:

1. A very light, HTML only, read only view of the whole database, where you can actually browse thru the clubs, championships, tourneys, players and ratings. You can see it in action on the public SoL instance at http://sol3.arstecnica.it/lit/.

2. A complete ExtJS based desktop-like application, that exposes all the functionalities described below in an easy to manage interface, that you can try out visiting http://sol3.arstecnica.it/.

Attention!

SoL 3 requires Python 3.3 or higher, it does not work with Python 2

Warning

SoL 3.1+ requires SQLite 3.8 or higher

Contents

• Goals

  • High level description

• Installation and Setup

  • The good old way

  • Pre-built Docker image

• Development

  • I18N / L10N

  • Feedback and support

  • Changes

Goals

These are the key points:

1. Multilingual application

   Scarry spoke only Italian, because the i18n mechanism in Delphi (and in general under Windows) sucks. Most of the code was written and commented in Italian too, and that made it very difficult to get foreign contributions

2. Multiuser

   There is a super user (named “admin” by default) that can do everything, in particular assign a nickname and a password to any player, who can then log in and manage her own tournaments, but can’t change information owned by other users

3. Real database

   Scarry used Paradox tables, but we are in the third millennium, now: SoL uses a real, even if simple and light, SQL database under its skin

4. Easy to use

   The application is usually driven by computer-illiterated guys, so little to no surprises

5. Easy to deploy

   Gods know how many hours went in building f*cking installers with BDE goodies

6. Bring back the fun

   Programming in Python is just that, since the beginning

High level description

The application implements the following features:

• basic tables editing, like adding a new player, opening a new championship, manually tweaking the scores, and so on;

• handle a single tourney

  1. compose a list of competitors: usually this is just a single player, but there are two people in doubles, or more (teams)

  2. set up the first round, made up of matches, each pairing two distinct competitors: if the tournament is associated with a rating this considers the Glicko2 rate of each player, otherwise uses a random pairing; either way, the tournament secretary is able to manually change the combinations

  3. print the game sheets, where the player will write the scores

  4. possibly show a countdown, to alert the end of the game

  5. insert the score of each match

  6. compute the new ranking

  7. print the current ranking

  8. possibly offer a way to withdraw some competitors, or to add a new competitor

  9. compute the next round

  10. repeat steps c. thru i. usually up to seven rounds

  11. possibly offer a way to go back, delete last round, correct a score and repeat

  12. if required, play up to three final rounds between the first two competitors

  13. recompute the ranking, assigning prizes

  14. update the rating the tournament is associated to

• handle a championship of tourneys

  • each tourney is associated to one championship

  • print the championship ranking

• data exchange, to import/export whole tourneys in a portable way

Installation and Setup

The very first requirement to install an instance of SoL on your own machine is getting Python 3.6 or better[1]. This step obviously depends on the operating system you are using: on most GNU/Linux distributions it is already available[2], for example on Debian and derivatives like Ubuntu the following command will do the task:

$ apt-get install python3

If instead you are using M$-Windows, you should select the right installer from the downloads page on http://www.python.org/.

Another recommended, although optional, add-on is the DejaVu fonts set, to support a rather wide range of glyphs when producing the PDFs printouts. As usual, on GNU/Linux it’s a matter of executing the following command

$ apt-get install fonts-dejavu

or equivalent for your distribution, while on M$-Windows you need to download them and extract the archive in the right location which usually is C:\Windows\Fonts.

The good old way

1. Install SoL using pip:

   pip install SoL

   that will download the latest version of SoL from PyPI and all its dependencies as well

2. Install ExtJS 4.2.1:

   python3 -m metapensiero.extjs.desktop

3. Create a standard config file:

   soladmin create-config config.ini

   and edit it as appropriate; you can also directly specify the name and the password of the super user (by default the name is admin and the password will be asked interactively):

   soladmin create-config --admin differentone --password str4nge

4. Setup the database:

   soladmin initialize-db config.ini

5. Load official data:

   soladmin restore config.ini

6. Run the application server:

   pserve config.ini

7. Enjoy!

   firefox http://localhost:6996/

   or, for poor Window$ users or just because using Python makes you happier:

   python -m webbrowser http://localhost:6996/

Pre-built Docker image

Note

This is a work-in-progress facility: better documentation and helper tools are on the way! It targets brave souls willing to face a bleeding edge experience.

Current state is based on the work contributed by Amar Sanakal, thank you!

Another option, if you have a 64bit computer, is to run the pre-built Docker image.

Requirements

First of all, you must enable the hardware virtualization in the BIOS of your computer.

Then you can proceed to install the Docker Engine for your particular operating system (that is, GNU/Linux, Windows or Mac OS X).

After you have tested the install in the Docker Quickstart terminal (for example as depicted here), run the following command in the same window:

docker run -d -p 80:6996 --name sol amarsanakal/solista

This will start the software and is now accessible on port 80. You can access it as http://<ip-address>.

The <ip-address> is the ip address of the docker machine running on your PC. This would have been displayed to you when you launched the Docker Quickstart terminal. You can check it anytime by running:

docker-machine ls

the ip address is shown under the URL column. Use that without the port number shown there. See https://docs.docker.com/machine/get-started/ for more details.

Developer’s playground

If you are a developer and want to play with Docker, you can checkout SoL sources and

• build an image with make docker-build

• change the admin credentials with make docker-change-admin

• start SoL within a Docker container with make docker-start, then visit http://localhost:6996/ as usual

See Makefile.docker for other related targets.

Roadmap

1. Provide some Unix shell scripts and Windows batch files to make the end users happier

2. Complete this section

3. Figure out how to build a new image on hub.docker.com whenever a new SoL release happens

Development

Since version 4 the development has been moved to GitLab: the previous repository on Bitbucket is now just a mirror, automatically kept in sync when new commits land on the primary one.

The complete sources can be downloaded with the following command:

git clone https://gitlab.com/metapensiero/SoL.git

I recommend using a virtual environment to keep you isolated from the system packages:

python3 -m venv env
source env/bin/activate

After that, you can setup a development environment by executing the command:

pip install -r requirements/development.txt

You must then install the required ExtJS 4 sources executing:

python -m metapensiero.extjs.desktop --src

If you are a developer, you are encouraged to create your own fork of the software and possibly open a pull request: I will happily merge your changes!

You can run the tests suite with either

make test

or with a more specific

pytest tests/models

I18N / L10N

Currently SoL is translated in English[3], French and Italian. If you know other languages and want to contribute, the easiest way to create a new translation is to create an account on the Weblate site and follow its translators guide.

Otherwise if like me you prefer using more traditional tools[4] you can extract a copy of the sources and operate directly on the local catalogs under the directory src/sol/locale.

To extract translatable messages use the following command:

make update-catalogs

To check your work you must compile them with:

make compile-catalogs

Feedback and support

If you run in troubles, or want to suggest something, or simply a desire of saying “Thank you” raises up, feel free to contact me via email as lele at metapensiero dot it.

Consider also joining the dedicated mailing list where you can get in contact with other users of the application. There is also an issues tracker where you can open a new tickets about bugs or enhancements.

---

[1]

As of this writing I’m using version 3.7.0 and I’d recommend using that, but SoL used to work great with any version higher than 3.4.

[2]

In fact it may even be already installed!

[3]

The are actually two distinct catalogs, to take into account US and UK variants.

[4]

GNU Emacs comes to mind of course, but there are zillions of them: start looking at the gettext page on Wikipedia.

Changes

4.0a4 (2020-01-18)

• New association between clubs and users: now a user may add a championship/tourney/rating/player only to clubs he either owns or is associated with

• Add a link to send an email to the instance’ admin on the login panel

4.0a3 (2020-01-13)

• Use a three-state flag for the player’s agreed privacy: when not explicitly expressed, SoL assumes they are publicly discernible if they participated to tournaments after January 1, 2020

• Player’s first and last names must be longer that one single character

4.0a2 (2020-01-11)

• Fix issue with UI language negotiation

• Use the better maintained Fomantic-UI fork of Semantic-UI in the “Lit” interface

• New tournaments delay compatriots pairing option

• Technicalities:

  • Official repository is now https://gitlab.com/metapensiero/SoL

  • NixOS recipes (thanks to [e-mail])

4.0a1 (2018-08-06)

Warning

Backward incompatible version

This release uses a different algorithm to crypt the user’s password: for this reason previous account credentials cannot be restored and shall require manual intervention.

It’s not possible to upgrade an existing SoL3 database to the latest version.

However, SoL4 is able to import a backup of a SoL3 database made by soladmin backup.

• Different layout for matches and results printouts, using two columns for the competitors to improve readability (suggested by Daniele)

• New tournaments retirements policy

• New “women” and “under xx” tourney’s ranking printouts

• New “self sign up” procedure

• New “forgot password” procedure

• New “agreed privacy” on players

• Somewhat prettier “Lit” interface, using Semantic-UI tables

• Technicalities:

  • Development moved to GitLab

  • Officially supported on Python 3.6 and 3.7, not anymore on <=3.5

  • Shiny new pytest-based tests suite

  • Uses python-rapidjson instead nssjson, as I officially declared the latter as abandoned

  • Uses PyNaCl instead of cryptacular, as the former is much better maintained

  • “Users” are now a separated entity from “players”: now the login “username” is a mandatory email and the password must be longer than five characters (was three before)