Skip to main content

Documentation Index

Fetch the complete documentation index at: https://mintlify.com/hxmz-axfn07/qr-printing-sfw/llms.txt

Use this file to discover all available pages before exploring further.

QR Print Station runs as a lightweight Python HTTP server that binds to every network interface on your machine. Once it is up, any customer on the same Wi-Fi network can scan the printed QR code, upload their documents, and set their print options — no app install required. This guide walks through the complete local-network setup from a fresh clone to a running server.

​
Prerequisites

Before you begin, make sure the following are available on the machine that will run the server:
  • Python 3.11 or newer — python3 --version
  • MySQL 5.7+ or MariaDB 10.3+ — the server uses PyMySQL with the utf8mb4 charset
  • pip — bundled with every modern Python installation

​
Installation

1

Create and activate a virtual environment

Isolate dependencies from your system Python installation:
python3 -m venv .venv
source .venv/bin/activate   # macOS / Linux
# .venv\Scripts\activate    # Windows
2

Install dependencies

All three runtime packages are pinned in requirements.txt:
.venv/bin/pip install -r requirements.txt
This installs:
  • qrcode[pil]==8.2 — QR code generation with Pillow image support
  • PyMySQL==1.1.1 — pure-Python MySQL driver
  • PyYAML==6.0.2 — config.yml parsing
3

Create the MySQL database and user

The bundled SQL file creates the qr_printing database, the qr_print_user account, and all four tables in one command:
mysql -u root -p < server/schema.sql
See the Database page for a full description of the schema and auto-migration behaviour.
4

Configure the environment file

Copy the example file and edit the values:
cp .env.example .env
Open .env in your editor and set at minimum:
PORT=8000
PUBLIC_URL=
QR_REFRESH_SECONDS=5
ADMIN_TOKEN=change-this-secret-token

MYSQL_HOST=127.0.0.1
MYSQL_PORT=3306
MYSQL_USER=qr_print_user
MYSQL_PASSWORD=change_me
MYSQL_DATABASE=qr_printing

PRINT_COMMAND=
Key values to change before going live:
VariableWhat to set
ADMIN_TOKENA long, random secret string — this becomes part of the admin dashboard URL
MYSQL_PASSWORDThe password you set for qr_print_user in MySQL
PORT(Optional) Change from 8000 if that port is already in use
5

Start the server

.venv/bin/python server.py
The server starts, initialises the database, generates the QR code, and prints its URLs to the terminal.

​
Startup Output

A successful start prints the local IP, all access URLs, and the path to the generated QR PNG: 
QR Print Station v2 running
Home:      http://192.168.1.100:8000/
Upload:    http://192.168.1.100:8000/upload
Admin:     http://192.168.1.100:8000/admin/your-secret-token
QR PNG:    qr-codes/upload.png
The IP address shown is auto-detected by opening a UDP socket toward 8.8.8.8 — it reflects whichever network interface routes outbound traffic, which is normally the local network adapter.

​
QR Code

On every startup the server writes qr-codes/upload.png — a PNG-encoded QR code that encodes the customer upload URL. Print this image or display it on a screen at the counter. Customers scan it with any smartphone camera app and are taken directly to the upload page. The QR code stays up-to-date automatically. A background thread wakes up every QR_REFRESH_SECONDS seconds (default 5) and calls get_upload_url(). It compares the result against the URL stored in qr-codes/.last_url. If the URL has changed — for example because PUBLIC_URL was updated in .env — or if the PNG file is missing, the thread regenerates qr-codes/upload.png immediately. You never need to restart the server to refresh the QR code.

​
Network Access

The server calls ThreadingHTTPServer with the bind address 0.0.0.0, which means it accepts connections on every available network interface. Any device connected to the same local network can open the upload page using the IP address shown in the startup output — for example http://192.168.1.100:8000/upload.

​
Firewall Note

If the host machine runs a software firewall (such as ufw, firewalld, or the Windows Defender firewall), you must allow inbound TCP connections on the configured PORT (default 8000). For example, on Ubuntu with ufw: 
sudo ufw allow 8000/tcp
Adjust the port number if you changed PORT in .env.
To give customers a public HTTPS URL — useful when the customer Wi-Fi is on a separate network segment or for remote management — see the ngrok deployment guide.
Do not expose QR Print Station directly to the public internet without placing it behind a reverse proxy that terminates TLS (such as Nginx or Caddy). The built-in HTTP server has no HTTPS support, no rate limiting, and no brute-force protection on the admin URL. Running it on a trusted local network only is strongly recommended for production use.

Build docs developers (and LLMs) love

Get started for freeTalk to us