Prerequisites

System Requirements

• UNIX-like Operating System
  • Linux (most extensively tested)
  • macOS and Windows (WSL) are supported

• Web Browser
  • Firefox most tested, Chrome & Edge & Safari ok, DuckDuckGo & Opera never tested.
  • Also works on mobile devices: tested on iPad

Docker Installation Requirements

• Git
• Docker and Docker Compose

Native (no container) Installation Requirements

• Git
• Python 3
  • Version 3.9 or higher
  • Virtual environment (venv) recommended

Docker Installation

Using Pre-built Images (Linux, Windows WSL, Mac)

Initial Setup

No local installation is required. Simply pull a SlowDash image from one of these official repositories:

• DockerHub: slowproj/slowdash:TAG
• GitHub Container Registry: ghcr.io/slowproj/slowdash:TAG

Select either a specific version tag from the repository or use latest for the most recent stable release.

Updating Docker Images

For users of the :latest tag from DockerHub or GitHub Container Registry, update to the newest version by running docker pull

$ docker pull slowproj/slowdash:latest

Building Images Locally

Initial Setup

$ git clone https://github.com/slowproj/slowdash.git
$ cd slowdash
$ make docker

Alternatively, you can execute these commands manually:

$ git clone https://github.com/slowproj/slowdash.git --recurse-submodules
$ cd slowdash
$ docker build -t slowdash .
$ docker build -t slowpy-notebook -f ./lib/slowpy/Dockerfile ./lib/slowpy

Updating Local Images

$ cd PATH/TO/SLOWDASH
$ make update
$ make docker

Or execute these commands manually (Important: Always include --recurse-submodules to avoid common integration issues):

$ cd PATH/TO/SLOWDASH
$ git pull --recurse-submodules
$ docker rmi -f slowdash slowpy-notebook
$ docker build -t slowdash .
$ docker build -t slowpy-notebook -f ./lib/slowpy/Dockerfile ./lib/slowpy

Native (no container) Installation

Setup

Using Virtual Environment (Recommended)

This installation method keeps all files contained within the git-cloned directory. You can completely remove the installation by deleting this directory.

$ git clone https://github.com/slowproj/slowdash.git --recurse-submodules
$ cd slowdash
$ make

This will create a bash file to set environmental variables. source it to include the settings:

$ source PATH/TO/SLOWDASH/bin/slowdash-bashrc

The contents of the file look like this:

export SLOWDASH_DIR=/PATH/TO/SLOWDASH
alias slowdash="$SLOWDASH_DIR/bin/slowdash"
alias slowdash-activate-venv="source $SLOWDASH_DIR/venv/bin/activate"

For permanent installation, it might be convenient to include the source command in the .bashrc (or .zshrc on Mac) file at your home directory.

System-wide Installation

$ git clone https://github.com/slowproj/slowdash.git --recurse-submodules
$ cd slowdash
$ make without-venv
$ pip install -r requirements.txt

Then activate the environment:

$ source bin/slowdash-bashrc

Verifying Installation

Verify your installation by running:

$ slowdash
Running in venv at /PATH/TO/SLOWDASH/venv
usage: 
  Web-Server Mode:      slowdash.py [Options] --port=PORT
  Command-line Mode:    slowdash.py [Options] COMMAND

Slowdash Version 250128 "Skykomish"

positional arguments:
  COMMAND               API query string. Ex) "config", "channels", "data/CHANNELS?length=LENGTH"

options:
  -h, --help            show this help message and exit
  -p PORT, --port PORT  port number for web connection; command-line mode without this option
  --project-dir PROJECT_DIR
                        project directory (default: current dir if not specified by SLOWDASH_PROJECT environmental variable)
...

Test the web interface by starting the server on a test port. You’ll see a warning about undefined project settings, which is expected at this stage:

$ slowdash --port=18881
23-05-15 20:12:35 WARNING: unable to find Slowdash Project Dir: specify it with the --project-dir option, set the SLOWDASH_PROJECT environmental variable, or run the slowdash commands at a project directory
listening at port 18881

$ firefox http://localhost:18881

If successful, you’ll see this configuration notice:

Press Ctrl-c to stop the server.

Updating Installation

$ cd PATH/TO/SLOWDASH
$ make update

Or manually execute:

$ cd PATH/TO/SLOWDASH
$ git pull --recurse-submodules
$ make

Running make is always safe, even if no updates are needed.

Browser Cache Management

After updating the SlowDash server, you may need to clear your browser’s cached scripts. To force a cache refresh, hold down the Shift key while clicking the reload button on any SlowDash page (“hard refresh”: the procedure might be different depending on the browser).