Skip to content

Getting started

Everything you need to get SQ running and tracking your first project.

SQ (short for Squirrel) is a lightweight, self-hosted project tracker: a kanban board per project, a Today's Tasks list, wall displays, and a built-in conscience that remembers every project you started. It is one Python service and one SQLite file, running on your own hardware, with no cloud account anywhere.

Quick start with Docker Compose

Clone the repository and bring the stack up:

git clone https://github.com/Syracuse3DPrintingOrg/ProjectTracker.git
cd ProjectTracker
docker compose up -d --build

Then open http://localhost:9280. The bundled docker-compose.yml publishes port 9280 and keeps all data in ./data next to the compose file.

Using the published image

If you would rather pull a ready-made image than build one, SQ is published as ghcr.io/syracuse3dprintingorg/projecttracker. This docker run matches what the compose file sets up:

docker run -d \
  --name projecttracker \
  -p 9280:9280 \
  -v /path/to/data:/data \
  --restart unless-stopped \
  ghcr.io/syracuse3dprintingorg/projecttracker:latest

Point the volume at any folder you like; that folder becomes the tracker's whole world (see below).

Unraid

Add a container with the image above, map port 9280, and map a path to /data. Nothing else is required. Later updates arrive through the container's own Check for Updates button.

Running without Docker

A plain Python install works too:

pip install -r service/requirements.txt
cd service && uvicorn app.main:app --host 0.0.0.0 --port 9280

Data lands in a data folder under the working directory; set TRACKER_DATA_DIR to move it.

Your first project

The first visit greets you with a welcome page. Give your project a name and SQ builds a board with Backlog, To Do, In Progress, and Done columns; rename, add, or reorder statuses whenever you like. Add cards, drag them between columns, and drag anything onto the Today rail to put it on your wall displays. That is the whole loop. The squirrel handles remembering.

Your first user

Out of the box SQ has no logins at all: anyone on your network can use it, which is fine on a trusted home LAN. To turn logins on, go to Settings, then Users and Access, and add the first user.

The first user must be an admin, and SQ will refuse anything less. Creating that user locks the instance for everyone, so the account that turns the key has to be able to manage settings, users, and backups afterward. From then on SQ also insists on keeping at least one active admin, so you can never lock yourself out by demoting the last one.

Wall displays and other devices are not affected by turning logins on; they authenticate with their own tokens (see the Administration page).

Where your data lives and what to back up

Everything is in the data folder (./data with the bundled compose file, /data inside the container):

Item What it holds
tracker.db The SQLite database: projects, columns, cards, users, API keys, activity
settings.json Everything saved from the Settings page, including AI keys and device tokens
secret_key The key that signs login sessions
attachments/ Every file attached to a card

Back up that one folder and you have everything. Settings also offers a one-click JSON download of your projects, columns, and cards; it is handy for moving boards around, but it is not the full picture (see Backup and restore on the Administration page).