Overprint

An eye on the printers.

A local dashboard for Klipper print farms: live status, repair history, print statistics, and G-code dispatch in one quiet, dark workspace.

Python · Flask · SQLite · Vanilla JavaScript · Raspberry Pi friendly

Quick start · Screenshots · How it works · Operations guide

---

Why Overprint?

A printer going offline and a printer needing a repair are different events. Overprint keeps connection state, print activity, and maintenance records together so you can see what is happening now and what has happened before.

Report a snapped belt, read the earlier reports, record the fix, and return the machine to service. Over time, the same notebook helps you spot recurring issues across a whole farm.

Screenshots

All images use generated demonstration records and reserved example IP addresses. They contain no real farm records, printer credentials, or personal names.

Printers

Grouped cards show live activity, current filenames, open repairs, and the last completed fix. Printing is yellow, Busy is blue, Ready is green, and repairs and errors stand out in red.

Repairs and fixes

Search the farm's repair log, filter open and fixed reports, and keep the original report beside the repair note and completion time.

See completed fixes

Overview

What it does

Area	Capabilities
Printer fleet	Search, group by model, filter by state, show last seen and last fixed, open Mainsail, and view each printer's notebook.
Live status	Ready, Printing, Busy/paused, Error, Offline, and Unknown. Open repair reports take priority over live state.
Maintenance	Report issues, record fix notes and dates, search history, correct mistakes, archive reports, and undo supported corrections.
Statistics	Print outcomes, approximate uptime, common repair reasons, and printer rankings across date ranges and model filters.
Send prints	Upload text G-code to selected printers or upload and start after confirmation and readiness checks. Track results per printer.
Storage	Inspect G-code storage and optionally clean eligible old files. Automatic deletion is off by default.
Appearance	Charcoal backgrounds with Light blue, Brown, Yellow, or Candy Red accents and responsive desktop/mobile layouts.
Local records	SQLite storage, consistent backup downloads, correction history, and a previewed manual history trim.

Quick start

Requires Python 3.10+. No Node.js build or frontend package installation is needed. A Raspberry Pi with a 64-bit OS is a suitable host; the app also runs on Windows, macOS, and Linux.

Raspberry Pi, Linux, or macOS

git clone https://github.com/xt-programmer/Overprint.git
cd Overprint
python3 -m venv .venv
.venv/bin/python -m pip install -r requirements.txt
.venv/bin/python app.py

Windows PowerShell

git clone https://github.com/xt-programmer/Overprint.git
cd Overprint
py -3 -m venv .venv
.\.venv\Scripts\python.exe -m pip install -r requirements.txt
.\.venv\Scripts\python.exe app.py

Open http://localhost:8080 on the host, or http://YOUR_SERVER_IP:8080 from another device on the same trusted network. The normal workspace starts empty and creates its database locally on first launch. Use --host 127.0.0.1 to listen only on your own computer, or --port to select a different port.

Try it without connecting printers

.venv/bin/python app.py --demo --host 127.0.0.1 --port 8081

On Windows, use .\.venv\Scripts\python.exe instead. Demo mode creates an isolated sample workspace in data/demo.db, does not start network workers, and blocks printer uploads and storage actions. No real printers are contacted. The repository includes the generator, no database files.

Connect your farm

1. Add a printer with its name, IPv4 address, and Moonraker port, usually 7125.
2. Optionally add its model, rack/location, and Moonraker API key. Model names become printer groups.
3. Enable Moonraker's [history] component to import print outcomes. The Overprint server must be able to reach each printer's Moonraker API.
4. Open a card to report an issue or read its notebook. Use Mark fixed to record the repair separately from the original report.
5. Choose your accent and monitoring settings under Settings, then save.

Mainsail links assume the printer's web interface is available over HTTP on port 80. Overprint uses Moonraker HTTP APIs and does not need SSH access to printers.

How it works

The browser talks to a Flask API served by Waitress. The host keeps printers, repairs, jobs, samples, and send results in SQLite and communicates with Moonraker over HTTP.

Browser → Overprint / Flask + Waitress → SQLite
                     ↓
              Moonraker HTTP API
                     ↓
                Klipper printers

Live checks run separately from history collection. They are staggered, with a target interval of about 30 seconds per printer; large farms and slow devices can take longer. The browser refreshes live data about every five seconds without replacing draft forms. Stale observations become Unknown.

History and optional uptime sampling run every 30 or 60 minutes. Uptime is an estimate from connection samples. Repair history stays available until you explicitly archive or trim it. Imported jobs and connection samples have a separate 365-day retention policy. Run one app process per workspace to avoid duplicating background workers.

Defaults and G-code cleanup

Setting	New workspace default
Automatic G-code deletion	Off
Uptime sampling	Off
Print-history collection	On
History/sample interval	30 minutes
Accent	Light blue

Check storage inspects files without deleting them. Clean now is a manual deletion action. Enabling Automatically delete unused G-code and saving settings opts into hourly cleanup.

Cleanup considers files in Moonraker's gcodes root, including subfolders. Files must be older than 72 hours by modification time. Printing, paused, loaded, queued, and recently uploaded files are protected, and state is checked again before each deletion. Unavailable or unverifiable printers are skipped. An idle printer can eventually have no saved G-code files. Deleted G-code must be resliced or uploaded again.

This switch controls printer-side G-code only, separately from history retention and manual database trimming. New defaults do not overwrite settings in an existing database.

Sending G-code

Use Send prints to select a text .gcode file up to 256 MB, then select printers by model, search, or ID ranges. Upload only stores it under overprint/<send-id>/ without starting a print. Upload & print requires confirmation and checks readiness before upload and again before starting.

Two transfers run concurrently. A send can partially succeed; inspect every printer's result. If a print-start response is lost, Overprint reports Check printer instead of automatically retrying the start. Check Mainsail before resubmitting.

Run as a Raspberry Pi service

For a fresh dedicated install:

sudo useradd --system --home /opt/overprint --shell /usr/sbin/nologin overprint
sudo mkdir -p /opt/overprint
sudo rsync -a --exclude=.git --exclude=.venv --exclude=data --exclude=test-results ./ /opt/overprint/
sudo python3 -m venv /opt/overprint/.venv
sudo /opt/overprint/.venv/bin/python -m pip install -r /opt/overprint/requirements.txt
sudo cp deploy/overprint.service /etc/systemd/system/overprint.service
sudo systemctl daemon-reload
sudo systemctl enable --now overprint

The service keeps records under /var/lib/overprint/. Check it with sudo systemctl status overprint or sudo journalctl -u overprint -f. See the operations guide for backups, restoring records, correction history, and database trimming.

Access and private data

Overprint is a shared workspace for a trusted local network. Everyone who can reach an unprotected instance can change records. It has no individual accounts or role-based permissions. Keep the app on your trusted network; use a secured reverse proxy or VPN for remote access.

Set PRINTFARM_PASSWORD to require HTTP Basic authentication. Any username is accepted; use HTTPS when transmitting a password. PRINTFARM_DB overrides the normal database location. For the service, place environment values in a root-readable /etc/overprint.env file and restart.

Printer API keys stay on the server and are not returned to the browser. Backups include those keys and must remain private. .gitignore excludes databases, environment files, logs, keys, uploads, backups, and local test artifacts. Do not add a live database or screenshots of your real workspace to a public fork.

Development and checks

.venv/bin/python -m unittest discover -s tests -v

Tests use temporary databases and simulated printer responses. They cover settings persistence, disabled-by-default cleanup, dispatch, monitoring, repairs, and maintenance. Optional browser checks:

.venv/bin/python -m pip install playwright
.venv/bin/python -m playwright install chromium
.venv/bin/python tests/browser_check.py
.venv/bin/python tests/browser_dispatch.py
.venv/bin/python tests/browser_live_state.py

app.py                 Routes and startup
printfarm/             Database, demo, monitoring, dispatch, maintenance, cleanup
templates/             HTML shell
static/                JavaScript, CSS, and icons; no build step
tests/                 Backend and optional browser checks
deploy/                Example systemd service
docs/                  Operations guide and anonymous screenshots

License

MIT.