Installation and Configuration Quick-Start

This page is designed to help you get an instance of CAT-SOOP up and running. If you are setting things up on a local copy, following the instructions on this page should be enough. If you are setting up a public-facing instance on a server you control, you should follow these instructions, and then continue by following the link at the bottom of this page for more information about server configuration.

As a general rule, catsoop is only ever really "officially" tested using Debian GNU/Linux, but others have tested these instructions on Mac OSX and on Windows (both WSL and Cygwin).

1) Install Necessary Software

CAT-SOOP depends on Python (version 3.8+, with pip and venv).

You will need Python version 3.8+ on your system to run CAT-SOOP. I'm sure that almost all distributions have Python 3.8+ in their package managers, though it may be necessary to download the source from the official Python site.

On Debian Bookworm, you will need the python3, python3-pip, and python3-venv packages (or a version of Python 3.8+ installed in some other way).

2) Download CAT-SOOP

There are several ways you can install CAT-SOOP.

2.1) Installation via pip

The easiest is pip, with a command like the following (for the most recent version):

$ pip3 install catsoop
Virtual Environments

We recommend installing catsoop in a virtual environment. If you want to install it to your system Python instead, you may need to run the above commands as root or use sudo.

2.2) Manual Installation

Alternatively, you can clone the repository with Mercurial:

$ hg clone

or the Git mirror:

$ git clone git://}/catsoop.git

After you have a local copy, you can then run:

$ make install

from the source directory. You can also run the unit tests by running:

$ make test

3) Configure CAT-SOOP

To configure CAT-SOOP, run the following command:

catsoop configure

and answer the questions it poses.


If you are running a public-facing CAT-SOOP instance, you are strongly encouraged to enable encryption if the directory in which you are storing the logs is not already encrypted in some way (e.g., via luks or gocryptfs or cryfs, etc).

4) Add Courses

The default location for CAT-SOOP courses is in ~/.local/share/catsoop/courses/. You should move (or symlink) your courses to that location.

If you're not sure what to put there, a decent place to start is with the "sample course", which you can put in the appropriate place with a command like the following, using Mercurial or Git:

$ hg clone ~/.local/share/catsoop/courses/sample_course


$ git clone git:// ~/.local/share/catsoop/courses/sample_course

5) Start CAT-SOOP

To start the server, you should run:

$ catsoop start

This will start the server listening on port 7667. You should then be able to directy your browser to http://localhost:7667 to see the CAT-SOOP instance.

6) Additional Configuration for Public-Facing Servers

If you are setting up a public-facing CAT-SOOP instance, see this page about additional server configuration as well.