Install and Configure StockManager

This guide covers everything you need to get StockManager installed and running from source on Linux, macOS, or Windows. It walks through system prerequisites, creating a Python virtual environment, installing Python packages, configuring environment variables, and choosing between the development server and the full desktop application mode. If you just want to take the application for a quick spin first, see the Quickstart.

Prerequisites

Before cloning the repository, make sure the following are available on your system:

Python 3.10 or newer — the application uses match statements, tomllib, and other features that require 3.10+. Python 3.12 is used in the official CI builds.
pip — comes bundled with Python 3.10+; run pip --version to confirm it’s available.
git — needed to clone the repository.
GTK 3 and WebKit2 (Linux only) — PyWebView’s Linux backend requires GTK 3 and the WebKit2 GTK bindings. These are system-level packages that cannot be installed via pip.

Install the Linux system dependencies with your package manager before proceeding:

# Ubuntu / Debian
sudo apt-get update
sudo apt-get install -y \
  python3-gi python3-gi-cairo \
  gir1.2-gtk-3.0 gir1.2-webkit2-4.1 \
  libgirepository-2.0-dev gcc libcairo2-dev \
  pkg-config python3-dev

# Arch Linux / Manjaro
sudo pacman -S python-gobject gtk3 webkit2gtk-4.1

# Fedora / RHEL
sudo dnf install python3-gobject gtk3 webkit2gtk4.1

On macOS and Windows no extra system packages are required — PyWebView uses the platform’s native WebView runtime (WebKit on macOS, WebView2 on Windows).

Installation

Clone the repository

Clone the StockManager source code to your local machine:

git clone https://github.com/InnoDev69/StockManager.git
cd StockManager

Create a virtual environment (recommended)

A virtual environment keeps StockManager’s dependencies isolated from other Python projects and from your system Python installation.

python -m venv .venv

Activate the environment:

# Linux / macOS
source .venv/bin/activate

# Windows (Command Prompt)
.venv\Scripts\activate.bat

# Windows (PowerShell)
.venv\Scripts\Activate.ps1

Your shell prompt should change to show (.venv) when the environment is active. Remember to activate it each time you open a new terminal session.

Install Python dependencies

Install all required packages from the pinned requirements.txt:

pip install -r requirements.txt

The file installs:

Package	Version	Purpose
`Flask`	3.0.0	Web framework and routing
`Werkzeug`	3.0.1	WSGI utilities, password hashing
`waitress`	2.1.2	Production WSGI server
`pywebview`	6.1	Native desktop window wrapper
`python-dotenv`	1.0.0	`.env` file loading
`requests`	unpinned	HTTP client for internal utilities
`python-barcode`	unpinned	Barcode generation for products
`Pillow`	unpinned	Image processing
`reportlab`	unpinned	PDF report generation
`pytz`	unpinned	Timezone handling
`cffi`	2.0.0	C Foreign Function Interface

On Linux, also install the Python GObject bindings that PyWebView needs:

pip install PyGObject pycairo

On Windows, install pythonnet for the WinForms-based PyWebView backend:

pip install pythonnet

Create the .env configuration file

Create a .env file in the project root directory. This file is loaded by python-dotenv on startup and must not be committed to version control.

# .env — minimum required configuration
FLASK_SECRET_KEY=replace-with-a-long-random-string

Generate a cryptographically secure secret key:

python -c "import secrets; print(secrets.token_hex(32))"

Add optional settings as needed (see Environment Variables below).

Environment Variables

All configuration is read from the .env file (or from the actual environment). The table below covers every supported variable.

Required

Variable	Description
`FLASK_SECRET_KEY`	Secret key used by Flask to sign session cookies and CSRF tokens. Must be a long, random, unpredictable string. The application runs without this set, but defaults to `"a"`, which is insecure and must not be used in any real deployment.

Server

The host, port, and thread count for the Waitress server are hardcoded in main.py (127.0.0.1:5000, 8 threads) and are not configurable via environment variables. To change them, edit the constants at the top of main.py before launching.

Database

Variable	Default	Description
`DB_PATH`	`./data/stock.db`	Path to the SQLite database file. Only applies in development mode; in the compiled desktop build the path is determined automatically per OS.

Email (optional)

These variables enable the password-reset flow, which sends a 6-digit recovery code to the user’s email address. All four must be set; the module-level EmailSender instance is created at import time and calls int(os.getenv('SMTP_PORT')), so a missing SMTP_PORT will raise a TypeError on startup. If email is not needed, omit all four variables and avoid importing the email module.

Variable	Description
`SMTP_SERVER`	Hostname of your SMTP server (e.g. `smtp.gmail.com`).
`SMTP_PORT`	SMTP port, typically `465` for SSL.
`SMTP_USERNAME`	The email address used as the sender and for authentication.
`SMTP_PASSWORD`	Password or app-specific password for SMTP authentication.

A fully populated .env looks like this:

# .env
FLASK_SECRET_KEY=a1b2c3d4e5f6...   # 64 hex chars recommended

# Optional: custom SQLite path (development only)
DB_PATH=./data/stock.db

# Optional: email for password reset
SMTP_SERVER=smtp.gmail.com
SMTP_PORT=465
SMTP_USERNAME=noreply@yourdomain.com
SMTP_PASSWORD=your-app-password

If you use Gmail, generate an App Password rather than your account password. Google blocks direct password authentication for SMTP when 2-Step Verification is enabled.

Running Modes

StockManager supports two distinct running modes that serve different purposes.

Development mode

python run-dev.py

This starts Flask’s built-in development server with debug=True. The server listens on http://127.0.0.1:5000 and can be accessed in any browser. Use this mode when developing, testing API calls, or exploring the application for the first time. Flask’s debug mode enables the Werkzeug reloader (restarts the server when Python files change) and produces detailed stack traces in the browser on any unhandled error.

Desktop application mode

python main.py

This is the full application mode. It starts Waitress (8 threads) in a background daemon thread, waits for the server to become reachable (up to 15 seconds), then opens a PyWebView window pointed at http://127.0.0.1:5000. The window is titled Stockly, opens at 1200×800, and enforces a minimum size of 800×600. The application exits cleanly when the window is closed: Waitress is shut down, the scheduler is stopped, and the SQLite connection pool is flushed.

	Development (`run-dev.py`)	Desktop app (`main.py`)
Server	Flask dev server	Waitress (8 threads)
Hot reload	✅ Yes	❌ No
Debug errors in browser	✅ Yes	❌ No
Native desktop window	❌ No	✅ Yes
Recommended for	Development, API testing	End-user deployment

First Run and Database Initialization

On the very first startup — regardless of mode — bd/bdInstance.py calls db.init_db(), which:

Creates the SQLite database file at the configured path (creating parent directories if necessary).
Creates all tables (users, items, sells, details, notifications, audit_log, and others) using CREATE TABLE IF NOT EXISTS — safe to run repeatedly.
Creates a set of composite indexes to optimise the sales and inventory queries.
Runs incremental column migrations (ALTER TABLE … ADD COLUMN IF NOT EXISTS) to bring older databases up to date.
Calls __create_default_root_user(), which inserts a root user with username root and password root1234 only if no root user already exists.
Validates that exactly one root user exists; if more than one is found, the application raises a critical error and refuses to start.

The SQLite file is created at ./data/stock.db in development mode. In the compiled desktop executable it is stored in a user-writable directory:

Linux / macOS: ~/.stock_manager/data/database.db
Windows: %APPDATA%\StockManager\data\database.db

The default root credentials (root / root1234) are well-known. Log in immediately after the first launch, go to the user settings page, and change the password before allowing anyone else to access the application.

Linux-Specific Notes

On Linux, main.py sets two environment variables before importing PyWebView to ensure stable GTK rendering:

os.environ.setdefault("PYWEBVIEW_GTK", "1")
os.environ.setdefault("WEBKIT_DISABLE_DMABUF_RENDERER", "1")

PYWEBVIEW_GTK=1 forces PyWebView to use the GTK/WebKit2 backend explicitly. WEBKIT_DISABLE_DMABUF_RENDERER=1 disables the DMA-BUF renderer in WebKit, which can cause blank windows or GPU-related crashes on certain Linux GPU drivers and virtual machines. If you encounter a white or blank window on Linux, verify that both variables are set before launching the application. You can also set them manually in your shell before running:

export PYWEBVIEW_GTK=1
export WEBKIT_DISABLE_DMABUF_RENDERER=1
python main.py

Pre-built Binaries

If you prefer not to run from source, the CI pipeline builds standalone executables using PyInstaller for three platforms on every tagged release:

Platform	File
Windows 10/11 (x64)	`Stockly-windows-x64.zip`
Ubuntu / Debian (x64)	`Stockly-ubuntu-x64.tar.gz`
Arch Linux / Manjaro (x64)	`Stockly-arch-x64.tar.gz`

Download the archive for your platform from the GitHub Releases page, extract it, and run the stockly (or stockly.exe) binary inside the extracted folder. No Python installation is required for the pre-built binaries.

Pre-built binaries on Linux still require the GTK and WebKit2 system libraries. Install them using your distribution’s package manager before launching the binary (see the Prerequisites section above).

Get Started

Core Features

Administration

Configuration

Install and Configure StockManager

Prerequisites

Installation

Environment Variables

Required

Server

Database

Email (optional)

Running Modes

Development mode

Desktop application mode

First Run and Database Initialization

Linux-Specific Notes

Pre-built Binaries

Build docs developers (and LLMs) love

Get Started

Core Features

Administration

Configuration

Documentation Index

​Prerequisites

​Installation

​Environment Variables

​Required

​Server

​Database

​Email (optional)

​Running Modes

​Development mode

​Desktop application mode

​First Run and Database Initialization

​Linux-Specific Notes

​Pre-built Binaries

Build docs developers (and LLMs) love

Prerequisites

Installation

Environment Variables

Required

Server

Database

Email (optional)

Running Modes

Development mode

Desktop application mode

First Run and Database Initialization

Linux-Specific Notes

Pre-built Binaries