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.

This guide walks you through cloning the project, creating the MySQL database, writing your environment file, and starting the server for the first time. By the end, you will have a running QR Print Station that customers on your local network can reach by scanning a QR code.
1

Clone and set up a virtual environment

Clone the repository, then create an isolated Python virtual environment and install the three required packages from requirements.txt:
git clone https://github.com/hxmz-axfn07/qr-printing-sfw.git
cd qr-printing-sfw
python3 -m venv .venv
.venv/bin/pip install -r requirements.txt
requirements.txt pins qrcode[pil]==8.2, PyMySQL==1.1.1, and PyYAML==6.0.2. No other runtime dependencies are needed — the HTTP server itself is pure Python stdlib.
2

Create the MySQL database and user

Run the bundled schema file against your MySQL instance as root. It creates the qr_printing database, a dedicated qr_print_user account with a password of change_me, and all four tables (orders, documents, pricing, settings), then seeds the pricing and settings tables with sensible defaults:
mysql -u root -p < server/schema.sql
After this command completes your database will contain:
TablePurpose
ordersOne row per customer submission, tracks status lifecycle
documentsOne row per uploaded file, linked to its parent order
pricingPer-combination price rules (paper size × color mode × print style)
settingsKey/value shop settings that override config.yml at runtime
If you need a different password or database name, edit server/schema.sql before running it and reflect the same values in .env (next step).
3

Configure .env

Copy .env.example to .env at the project root and fill in your values. Every variable is described inline below:
# TCP port the HTTP server listens on (default: 8000)
PORT=8000

# Optional public URL (e.g. ngrok tunnel). When set, the QR code points here
# instead of the local IP. Leave blank for LAN-only use.
PUBLIC_URL=

# How often (in seconds) the background thread checks whether the QR needs
# to be regenerated (e.g. because PUBLIC_URL changed). Default: 5
QR_REFRESH_SECONDS=5

# Secret token embedded in the admin URL: /admin/<ADMIN_TOKEN>
# Change this to a long, random string before exposing the server.
ADMIN_TOKEN=change-this-secret-token

# MySQL connection settings — must match the database you created above
MYSQL_HOST=127.0.0.1
MYSQL_PORT=3306
MYSQL_USER=qr_print_user
MYSQL_PASSWORD=change_me
MYSQL_DATABASE=qr_printing

# Optional shell command to send a file to a physical printer.
# Supports placeholders: {file}, {copies}, {paper}, {color}, {style}
# Leave blank to manage printing manually.
PRINT_COMMAND=
4

Start the server

Run server.py from the project root using the virtual environment interpreter:
.venv/bin/python server.py
The process stays in the foreground and logs every request to stdout. You should see startup output similar to the following:
QR Print Station v2 running
Home:      http://192.168.1.42:8000/
Upload:    http://192.168.1.42:8000/upload
Admin:     http://192.168.1.42:8000/admin/change-this-secret-token
QR PNG:    /home/user/qr-printing-sfw/qr-codes/upload.png
On first startup the server also initialises any missing database tables and runs schema migrations, so it is safe to restart after upgrading.
5

Access the interfaces

With the server running, open a browser on the same network. Replace <host> with the IP or hostname shown in the startup output and <token> with your ADMIN_TOKEN value.
InterfaceURL
Shop home (shows QR)http://<host>:8000/
Customer upload flowhttp://<host>:8000/upload
Admin dashboardhttp://<host>:8000/admin/<token>
Generated QR code PNGqr-codes/upload.png (local file, also served via the home page)
Point a phone camera at the QR displayed on the home page to test the full customer flow. The QR image encodes the /upload URL and is regenerated automatically whenever the target address changes.
To accept orders from customers outside your local network — or to test from a phone on mobile data — expose the server through a tunnel such as ngrok. Set PUBLIC_URL to the tunnel URL (e.g. https://abc.ngrok-free.app) in .env and the QR code will update within QR_REFRESH_SECONDS seconds without a restart. See Deploying with ngrok for a step-by-step guide.

Build docs developers (and LLMs) love

Get started for freeTalk to us