Windows Installer

Windows Installer

The Windows installer sets up Printbuddy natively on Windows without Docker.

It checks the required tools, clones Printbuddy, creates a Python virtual environment, installs dependencies, creates separate data and log directories, creates a start script, adds optional firewall access, and can register Printbuddy as a Windows Service.

Script path: /install/windows-installer.ps1

Quick Start

Run PowerShell as Administrator and start the installer:

powershell -ExecutionPolicy Bypass -Command "iwr -useb https://raw.githubusercontent.com/vmhomelab/printbuddy/main/install/windows-installer.ps1 -OutFile windows-installer.ps1; .\windows-installer.ps1"

The installer will guide you through the setup.

It asks for:

• Installation directory
• Printbuddy port
• Whether Printbuddy should listen on the LAN or only on this computer
• Firewall rule creation
• Optional Windows Service registration

Recommended: Use the default installation path unless you have a specific reason to change it.

Unattended install

For managed deployments, add parameters after .\windows-installer.ps1 in the same one-liner:

powershell -ExecutionPolicy Bypass -Command "iwr -useb https://raw.githubusercontent.com/vmhomelab/printbuddy/main/install/windows-installer.ps1 -OutFile windows-installer.ps1; .\windows-installer.ps1 -Port 8010 -Yes"

Installer Parameters

You can pass parameters directly after .\windows-installer.ps1 in the download one-liner or when running a previously downloaded copy.

• -InstallDir <Path>

  • Default: C:\Printbuddy
  • Installation directory. The Git checkout is placed in InstallDir\printbuddy; data and logs are stored as sibling folders.

• -Port <1-65535>

  • Default: 8000
  • HTTP port used by Printbuddy. The installer checks whether the selected port is already in use.

• -Yes

  • Default: off
  • Non-interactive mode. Accepts the default answer for yes/no prompts.

• -Silent

  • Default: off
  • Non-interactive mode with reduced console output.

• -NoService

  • Default: off
  • Skip Windows Service registration.

• -NoStart

  • Default: off
  • Do not start Printbuddy at the end of installation.

• -LocalOnly

  • Default: off
  • Bind Printbuddy to 127.0.0.1 instead of exposing it on all LAN interfaces.

Examples:

powershell -ExecutionPolicy Bypass -Command "iwr -useb https://raw.githubusercontent.com/vmhomelab/printbuddy/main/install/windows-installer.ps1 -OutFile windows-installer.ps1; .\windows-installer.ps1 -Port 8010 -Yes"

powershell -ExecutionPolicy Bypass -Command "iwr -useb https://raw.githubusercontent.com/vmhomelab/printbuddy/main/install/windows-installer.ps1 -OutFile windows-installer.ps1; .\windows-installer.ps1 -InstallDir C:\PrintbuddyLocal -Port 8011 -Yes -NoService -NoStart -LocalOnly"

Default Installation Path

By default, Printbuddy is installed to:

C:\Printbuddy

The default installation path is C:\Printbuddy instead of C:\Program Files\Printbuddy because Printbuddy is a Git-based Python application that creates and updates a virtual environment, writes log files, and may be updated through git pull.

Using C:\Printbuddy avoids common permission, UAC, path escaping, and service-context issues on Windows.

Custom path supported: During setup, the installer asks whether the default path should be used. You can provide a custom installation path if needed.

Data and Log Directories

The installer keeps user data outside the Git checkout so updates and re-clones do not remove the database, archives, uploads, or logs.

Typical layout:

C:\Printbuddy\
├─ printbuddy\       # Git checkout
├─ data\             # Persistent application data
├─ logs\             # Runtime and application logs
├─ install.log       # Installer log
└─ Start-Printbuddy.ps1

Administrator Rights

The installer should be started from an elevated PowerShell session.

Administrator rights are needed for:

• Installing Git or Python via winget when they are missing
• Creating the installation directory and fixing permissions
• Creating a Windows Firewall rule
• Registering Printbuddy as a Windows Service

If the script is not elevated, it may try to relaunch itself as Administrator.

Git Detection

The installer checks whether git is available.

If Git is missing, the installer can install it through winget.

After Git is available, the installer clones or updates:

https://github.com/vmhomelab/printbuddy.git

Python Detection

The installer checks whether a supported Python 3 runtime is available.

If Python is missing, the installer can install it through winget.

After Python is available, the installer creates a virtual environment and installs Printbuddy requirements inside that environment.

Installation Flow

The installer performs these steps:

1. Creates or validates the install directory.
2. Starts installer logging.
3. Checks administrator rights.
4. Checks Git and Python.
5. Clones or updates the Printbuddy repository.
6. Creates persistent data and log directories.
7. Creates a Python virtual environment.
8. Installs backend dependencies.
9. Selects the HTTP port and bind address.
10. Creates Start-Printbuddy.ps1.
11. Optionally creates a Windows Firewall rule.
12. Optionally registers a Windows Service.
13. Optionally starts Printbuddy.

Port Selection

The default web port is:

8000

If the selected port is already in use, choose another port, for example:

.\windows-installer.ps1 -Port 8010

LAN Access

By default, the installer can expose Printbuddy on the LAN so other devices in your network can open it.

Use -LocalOnly to bind only to this computer:

.\windows-installer.ps1 -LocalOnly

Local-only mode is useful when Printbuddy is accessed through a local browser only, or when another reverse proxy handles external access.

Firewall Rule

When LAN access is enabled, the installer can create a Windows Firewall rule for the selected port.

If you skip the firewall rule, Printbuddy may start correctly but be unreachable from other devices until the port is allowed manually.

Generated Start Script

The installer creates:

Start-Printbuddy.ps1

Use it to start Printbuddy manually from the install directory.

Logging

The installer and runtime use separate logs.

Typical logs:

• install.log — installer actions and errors
• Runtime log — PowerShell/service startup output
• Application logs — Printbuddy backend logs

Logs are kept outside the Git checkout where possible so updates do not remove them.

Windows Service

The installer can register Printbuddy as a Windows Service so it starts automatically with Windows.

NSSM

The service registration uses NSSM where supported. NSSM runs the generated PowerShell start script as a Windows Service and captures service output.

Managing the Service

Useful service commands:

Get-Service Printbuddy
Start-Service Printbuddy
Stop-Service Printbuddy
Restart-Service Printbuddy

Automatic Startup

If service registration is enabled, Printbuddy starts automatically after Windows boots.

Use -NoService if you prefer to start it manually.

Updating

If Printbuddy was installed from Git, update from the Git checkout:

cd C:\Printbuddy\printbuddy
git pull

Then restart the service or start script:

Restart-Service Printbuddy

If you are not using the Windows Service, stop the running PowerShell window and run Start-Printbuddy.ps1 again.

Useful Commands

Manual Start

cd C:\Printbuddy
.\Start-Printbuddy.ps1

View Service Status

Get-Service Printbuddy

View Runtime Logs

Get-Content C:\Printbuddy\logs\runtime.log -Tail 100 -Wait

View Application Logs

Get-ChildItem C:\Printbuddy\logs

View Runtime Errors

Get-Content C:\Printbuddy\logs\runtime-error.log -Tail 100 -Wait

Remove Service

Stop-Service Printbuddy
sc.exe delete Printbuddy

Troubleshooting

Installer log is locked

Close other PowerShell windows or editors that have install.log open, then run the installer again.

Runtime log is locked

Stop the Printbuddy service or close the manual start window before deleting or moving runtime logs.

Service does not start

Check the service status and runtime logs:

Get-Service Printbuddy
Get-Content C:\Printbuddy\logs\runtime-error.log -Tail 100

Also verify that the configured port is free.

Delete and recreate the service

Stop-Service Printbuddy
sc.exe delete Printbuddy
.\windows-installer.ps1 -Yes

Git clone fails

Check internet access, DNS, and whether GitHub is reachable from the Windows host.

You can test Git manually:

git ls-remote https://github.com/vmhomelab/printbuddy.git

Port already in use

Choose another port:

.\windows-installer.ps1 -Port 8010

Non-English Windows permissions

If directory permission changes fail on a non-English Windows installation, run PowerShell as Administrator and use a simple install path such as:

C:\Printbuddy

Avoid installing into C:\Program Files unless you specifically need that layout.

Security Notes

• Run the installer from the official Printbuddy repository only.
• Review the script before running it in production.
• Use -LocalOnly if you do not want Printbuddy listening on the LAN.
• Only open the Windows Firewall port on trusted networks.
• Keep the Windows host patched and restrict access to the Printbuddy UI.

Next Steps

After installation:

1. Open Printbuddy in your browser.
2. Create or complete the initial setup.
3. Add your first printer.
4. Configure backups before storing important archive data.
5. Review firewall and authentication settings before exposing the instance beyond your local machine.