Printventory

Version 1.22.1

Printventory is an Electron-based desktop application for managing your 3D printing model collection. It helps you organize, catalog, and manage STL and 3MF files with powerful features including automatic scanning, thumbnail generation, tagging, and duplicate detection.

Features

Core Functionality

• Directory Scanning: Automatically scan and catalog STL and 3MF files (up to 50MB per file)
• 3D Model Preview: View thumbnails of your 3D models with customizable background colors
• File Management: Quick access to file locations, delete files with database cleanup
• Database Backup & Restore: Protect your data with backup and restore functionality

Organization & Metadata

• Tagging System: Organize models with custom tags and categories
• Designer Tracking: Assign and track designer information for each model
• Print Status: Track whether models have been printed, planned, or are in progress
• Source URLs: Store links to where you found or purchased models
• Notes: Add custom notes to any model
• Parent/Child Relationships: Link related models together
• License Tracking: Assign licenses to models

Advanced Features

• Server Mode: Run Printventory as a web server accessible from any device on your local network (see Server Mode section for details)
• Multi-Edit Mode: Select and edit multiple models simultaneously for batch operations
• Duplicate Detection: Find duplicate files based on content hash with visual comparison
• Print Roulette: Randomly select models from your collection
• AI Tagging: Automated tag suggestions using AI
• Search & Filter: Real-time search by filename and filter by designer, tags, print status, parent model, or license
• Tag Manager: Comprehensive tag management interface
• Metadata Editor: Bulk metadata editing capabilities
• Thumbnail Management: Generate, regenerate, or purge model thumbnails

User Interface

• Responsive Grid Layout: Browse models in an intuitive grid view
• Context Menu: Quick actions via right-click menu
• Sort Options: Sort by name, size, or date
• Auto-save: Changes are automatically saved

For a complete list of features and detailed usage instructions, see the GUIDE.md file.

Installation

Pre-built Releases

Download the latest release for your platform: - Windows: Printventory-Setup-1.22.5.exe (NSIS installer) - macOS: Universal binary (Intel and Apple Silicon) DMG - Linux/Docker: printventory-docker-1.22.5.zip (Docker distribution package)

Data Storage

• Windows: %LOCALAPPDATA%\Printventory
• macOS: ~/Library/Application Support/Printventory

The database and thumbnails are preserved during updates. Backups are automatically created before updates.

Server Mode

Printventory can run in Server Mode, allowing you to access your 3D model library from any device on your local network through a web browser. This is particularly useful for accessing your collection from multiple computers or devices without installing the application on each one.

What is Server Mode?

Server Mode runs Printventory as an HTTP server on port 5000, making it accessible from any device on your local network through a web browser. The application interface is served via HTTP, and all functionality remains available remotely.

Starting Server Mode

To start Printventory in Server Mode, launch it with the --server flag:

Windows:

printventory.exe --server

Command Line:

printventory --server

The server will start and continue running until you close the application. You'll see console output indicating the server is running:

Printventory server mode started
Server running at http://0.0.0.0:5000
Access from remote browsers: http://<your-ip>:5000
Server mode requires UNC paths for all file operations

Accessing the Server

Once started, you can access Printventory from any browser on your network:

http://<your-computer-ip>:5000

For example, if your computer's IP address is 192.168.1.100:

http://192.168.1.100:5000

Important Requirements

• Path Requirements:
• Windows Server Mode: Requires UNC (Universal Naming Convention) paths for all file operations
  • UNC paths use the format: \\server\share\path\to\file
  • Local drive paths (C:\, D:\, etc.) will not work in Server Mode
• Docker/Linux Server Mode: Uses Linux-style absolute paths (e.g., /mnt/network-share/path/to/file)
  • Network shares must be mounted into the container (see Docker Deployment)
• Network Access: The server listens on all network interfaces (0.0.0.0) on port 5000
• Firewall: You may need to allow Printventory through your firewall to access it from other devices
• Network Security: Server Mode is designed for local network use. For production deployments, consider additional security measures
• STL Home Setting: The STL Home setting follows the same path format rules as regular scanning. See the STL Home Setting section below for details on automatic and periodic scanning.

Use Cases

• Access your model library from multiple computers on the same network
• Browse your collection from tablets or mobile devices
• Share your library with others on your local network
• Centralized model management for a team or workshop

Docker Deployment

Printventory can also be deployed as a Docker container for Linux server mode deployment. See the Docker Deployment section for detailed instructions.

STL Home Setting

The STL Home setting allows automatic scanning of a directory on startup and, in server mode, periodic scanning for new files. This is particularly useful for keeping your library up-to-date automatically.

Setting STL Home in Server Mode

1. Access the Printventory web interface at http://<your-ip>:5000
2. Navigate to Settings → STL Home
3. Enter the directory path:
4. Windows Server Mode: Use UNC path format (e.g., \\server\share\models)
5. The path must be accessible from the server machine
6. Configure the Update Frequency (default: 60 minutes):
7. This determines how often the STL Home directory is automatically scanned for new files
8. Range: 1-1440 minutes (1 minute to 24 hours)
9. Click Save

How It Works

• On Startup: When Printventory starts in server mode, it automatically scans the STL Home directory if one is configured
• Periodic Scanning: In server mode, Printventory will automatically scan the STL Home directory at the configured interval
• Path Requirements: STL Home paths follow the same format rules as regular scanning:
• Windows Server Mode: Must use UNC paths (\\server\share\path)
• Paths are validated when saved
• Background Scanning: Periodic scans run in the background and won't disrupt the web interface

Clearing STL Home

To disable automatic scanning, clear the STL Home directory field and save. This will stop both startup and periodic scanning.

Getting Help

For more information about Server Mode, use the Help > Server Mode Info menu item in the application, which provides detailed information and instructions including Docker deployment options.

Building from Source

Prerequisites

Before building Printventory from source, ensure you have the following installed:

• Node.js (v16.x or later recommended)
• npm (v8.x or later)
• Git
• Platform-specific build tools:
• Windows: Visual Studio Build Tools with C++ development workload
• macOS: Xcode Command Line Tools (xcode-select --install)

Clone the Repository

git clone https://github.com/yourusername/printventory.git
cd printventory

Install Dependencies

Install all required dependencies:

npm install

This will also run the postinstall script to install app-specific dependencies (including native modules like better-sqlite3).

Development Mode

To run the application in development mode:

npm start

This will launch the Electron application.

Building for Production

Build for All Platforms

To build the application for both macOS and Windows:

npm run build

Build for macOS Only

To build a universal macOS application (Intel and Apple Silicon):

npm run build:mac

Build for Windows Only

To build for Windows:

npm run build:win

Build for Linux AppImage (from Windows)

To build a Linux AppImage from Windows, you need either WSL (Windows Subsystem for Linux) or Docker:

Prerequisites: - Option 1 (Recommended): WSL with Node.js installed - Install WSL: wsl --install - Install Node.js in WSL: wsl sudo apt-get update && wsl sudo apt-get install -y nodejs npm - Option 2: Docker Desktop - Install from: https://www.docker.com/products/docker-desktop

Build Command:

npm run build:linux

Or using PowerShell:

.\scripts\build-linux-appimage.ps1

The script will automatically detect and use WSL if available, otherwise it will fall back to Docker. The AppImage will be generated in the dist directory.

Note: The first build may take longer as dependencies need to be installed in the Linux environment.

All build outputs will be generated in the dist directory.

Docker Deployment (Linux Server Mode)

Printventory can be deployed as a Docker container for easy server mode deployment on Linux systems. This is ideal for headless servers or containerized environments.

Distribution Options

Option 1: Pre-built Distribution Package (Recommended) - Download printventory-docker-${version}.zip from releases - Extract and run: docker-compose up -d

Option 2: Build from Source - Clone the repository and build the Docker image yourself - See "Building the Docker Image" section below

Option 3: Docker Hub (Recommended for Quick Deployment) - Pull and run the pre-built image from Docker Hub - No need to build from source - see "Pulling from Docker Hub" section below

Pulling from Docker Hub

If the Printventory Docker image has been published to Docker Hub, you can pull and run it directly without building from source.

Prerequisites

• Docker installed
• Docker Desktop running (if on Windows/Mac)

Pulling the Image

Pull the latest version:

docker pull printventory/printventory:latest

Pull a specific version:

docker pull printventory/printventory:1.23.0

The image is available on Docker Hub at: https://hub.docker.com/r/printventory/printventory

Running with Docker Run

Basic run command:

docker run -d \
  --name printventory-server \
  -p 5000:5000 \
  -v ./data:/root/.config/Printventory \
  --restart unless-stopped \
  printventory/printventory:latest

With network share mounted (Windows - mapped drive):

# Step 1: Map the network share to a drive letter on Windows
net use Z: \\server\share /persistent:yes

# Step 2: Run container with volume mount and STL_HOME environment variable
# Maps Windows Z: drive to /mnt/network-share inside container
docker run -d \
  --name printventory-server \
  -p 5000:5000 \
  -v ./data:/root/.config/Printventory \
  -v Z:/:/mnt/network-share:ro \
  -e STL_HOME=/mnt/network-share/models \
  --restart unless-stopped \
  printventory/printventory:latest

# Step 3: Use Linux-style paths in Printventory
# Example: /mnt/network-share/models/myfile.stl
# STL Home is automatically configured via STL_HOME environment variable

With network share mounted (Linux - SMB/CIFS):

# Step 1: Mount the network share on the Linux host
sudo mkdir -p /mnt/network-share
sudo mount -t cifs //server/share /mnt/network-share -o username=user,password=pass,uid=$(id -u),gid=$(id -g)

# Step 2: Run container with volume mount and STL_HOME environment variable
# Maps host /mnt/network-share to /mnt/network-share inside container
docker run -d \
  --name printventory-server \
  -p 5000:5000 \
  -v ./data:/root/.config/Printventory \
  -v /mnt/network-share:/mnt/network-share:ro \
  -e STL_HOME=/mnt/network-share/models \
  --restart unless-stopped \
  printventory/printventory:latest

# Step 3: Use Linux-style paths in Printventory
# Example: /mnt/network-share/models/myfile.stl
# STL Home is automatically configured via STL_HOME environment variable

Running with Docker Compose

Create a docker-compose.yml file:

```yaml version: '3.8'

services: printventory: image: printventory/printventory:latest container_name: printventory-server ports: - "5000:5000" volumes: # Persist database and application data to local directory # Database is stored in ./data directory on the host filesystem # This ensures data persists when the image is updated - ./data:/root/.config/Printventory

  # Option 1: Mount Windows mapped drive (Windows Docker Desktop)
  # First, map network share: net use Z: \\server\share /persistent:yes
  # Then uncomment the line below and use /mnt/network-share in Printventory
  # - Z:/:/mnt/network-share:ro

  # Option 2: Mount Linux SMB/CIFS share (Linux host)
  # First, mount on host: sudo mount -t cifs //server/share /mnt/network-share -o username=user,password=pass
  # Then uncomment the line below and use /mnt/network-share in Printventory
  # - /mnt/network-share:/mnt/network-share:ro

  # Option 3: Mount local directory (if files are on Docker host)
  # Example: mount host /home/user/models to