Windows Installer¶

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

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

Quick Start¶

Run PowerShell as Administrator and start the installer:

powershell -ExecutionPolicy Bypass -Command "iwr -useb https://raw.githubusercontent.com/maziggy/bambuddy/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
• Bambuddy port
• Whether Bambuddy should listen on the LAN or only on this computer
• Firewall rule creation
• Optional Windows Service registration

powershell -ExecutionPolicy Bypass -Command "iwr -useb https://raw.githubusercontent.com/maziggy/bambuddy/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.

Examples:

powershell -ExecutionPolicy Bypass -Command "iwr -useb https://raw.githubusercontent.com/maziggy/bambuddy/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/maziggy/bambuddy/main/install/windows-installer.ps1 -OutFile windows-installer.ps1; .\windows-installer.ps1 -InstallDir C:\BambuddyLocal -Port 8011 -Yes -NoService -NoStart -LocalOnly"

Default Installation Path¶

By default, Bambuddy is installed to:

C:\Bambuddy

The default installation path is C:\Bambuddy instead of C:\Program Files\Bambuddy because Bambuddy 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:\Bambuddy avoids common permission, UAC, path escaping, and service-context issues on Windows.

Data and Log Directories¶

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

Default layout:

C:\Bambuddy\bambuddy   Git checkout
C:\Bambuddy\data       Database, archives, and application data
C:\Bambuddy\logs       Bambuddy application logs

The generated start script sets:

$env:DATA_DIR = "C:\Bambuddy\data"
$env:LOG_DIR  = "C:\Bambuddy\logs"

When Bambuddy is registered as a Windows Service, the same values are passed to NSSM through AppEnvironmentExtra.

Administrator Rights¶

The installer checks whether it is running with administrator rights.

If it is not elevated, it relaunches itself through UAC.

Administrator rights are required for:

• Installing Git or Python with winget
• Creating firewall rules
• Adjusting folder permissions
• Registering Bambuddy as a Windows Service
• Replacing an existing Bambuddy service

Git Detection¶

The installer checks whether Git is available.

If Git is missing, it installs Git automatically with winget:

winget install --id Git.Git --exact --silent --accept-package-agreements --accept-source-agreements

After installation, the script refreshes the current PowerShell PATH.

Python Detection¶

The installer checks for Python 3.10 or newer using:

python --version
py -3 --version

If Python 3.10+ is missing, it installs Python automatically with winget:

winget install --id Python.Python.3.12 --exact --silent --accept-package-agreements --accept-source-agreements

Installation Flow¶

The installer performs the following setup steps:

git clone https://github.com/maziggy/bambuddy.git
cd bambuddy
python -m venv venv
.\venv\Scripts\python.exe -m pip install --upgrade pip
.\venv\Scripts\pip.exe install -r requirements.txt

Fresh installs use a shallow clone for faster setup:

git clone --depth=1 https://github.com/maziggy/bambuddy.git

The generated start script runs Bambuddy with Uvicorn. By default the installer asks whether Bambuddy should be exposed on the LAN. If you choose LAN access, it binds to 0.0.0.0; otherwise it binds to 127.0.0.1.

.\venv\Scripts\python.exe -m uvicorn backend.app.main:app --host 0.0.0.0 --port 8000

Port Selection¶

During setup, the installer asks which port Bambuddy should use.

Default port:

8000

Example URLs:

http://localhost:8000
http://<windows-host-ip>:8000

LAN Access¶

The installer asks whether Bambuddy should be reachable from other devices on the local network.

For unattended local-only installs, use:

.\windows-installer.ps1 -Yes -LocalOnly

Firewall Rule¶

The installer can optionally create an inbound Windows Firewall rule for the selected port.

Example rule:

The rule intentionally excludes the Public profile so that Bambuddy is not reachable on untrusted networks (cafe, hotel, airport Wi-Fi) where Windows tags the connection as Public. If Bambuddy should only be accessed locally, the firewall rule is optional.

Generated Start Script¶

The installer creates a reusable start script:

C:\Bambuddy\Start-Bambuddy.ps1

Manual start:

powershell.exe -ExecutionPolicy Bypass -File "C:\Bambuddy\Start-Bambuddy.ps1"

The start script:

• Sets the Bambuddy working directory
• Sets DATA_DIR and LOG_DIR
• Uses the virtual environment Python executable
• Starts Uvicorn
• Uses the selected port and bind address

Logging¶

The installer creates installer and service wrapper logs in the installation directory. Bambuddy's own application logs are written to C:\Bambuddy\logs.

Default paths:

C:\Bambuddy\install.log
C:\Bambuddy\bambuddy-runtime.log
C:\Bambuddy\bambuddy-runtime-error.log
C:\Bambuddy\logs\

Windows Service¶

At the end of the installation, the installer asks whether Bambuddy should be registered as a Windows Service.

If enabled, Bambuddy can:

• Start automatically after a Windows reboot
• Run without an open PowerShell window
• Be controlled with Windows service commands
• Restart automatically if the process exits unexpectedly

Service name:

Bambuddy

NSSM¶

The installer uses NSSM to run Bambuddy as a Windows Service.

NSSM is used because a normal PowerShell script or Python process does not behave like a native Windows Service by itself.

The installer stores NSSM in:

C:\Bambuddy\nssm\nssm.exe

The NSSM ZIP archive is verified with SHA256 before extraction.

Managing the Service¶

Check status:

Get-Service Bambuddy

Start:

Start-Service Bambuddy

Stop:

Stop-Service Bambuddy

Restart:

Restart-Service Bambuddy

Show service configuration:

sc.exe qc Bambuddy

Check startup mode:

Get-CimInstance Win32_Service -Filter "Name='Bambuddy'" |
Select-Object Name, State, StartMode, PathName

Expected startup mode:

StartMode : Auto

Automatic Startup¶

When registered as a Windows Service, Bambuddy starts automatically after a system reboot.

The NSSM service is configured with:

SERVICE_AUTO_START

The process restart behavior is configured as:

AppExit Default Restart
AppExit 0 Exit
AppRestartDelay 5000

Exit code 0 is treated as a clean stop (the service stays stopped), and any other exit — including segfaults, OOM kills, and unhandled signals — triggers a restart after a 5-second delay. This matches the Linux installer's Restart=on-failure semantics, so the production resilience is the same on both platforms.

Updating¶

If the Bambuddy repository already exists, the installer can update it with:

git pull

After updating, dependencies are installed again from requirements.txt.

Runtime data stays in C:\Bambuddy\data and logs stay in C:\Bambuddy\logs, so the Git checkout can be updated or re-cloned without deleting user data.

Stop-Service Bambuddy
.\windows-installer.ps1
Start-Service Bambuddy

Useful Commands¶

Manual Start¶

powershell.exe -ExecutionPolicy Bypass -File "C:\Bambuddy\Start-Bambuddy.ps1"

View Service Status¶

Get-Service Bambuddy

View Runtime Logs¶

Get-Content "C:\Bambuddy\bambuddy-runtime.log" -Tail 100 -Wait

View Application Logs¶

Get-Content "C:\Bambuddy\logs\bambuddy.log" -Tail 100 -Wait

View Runtime Errors¶

Get-Content "C:\Bambuddy\bambuddy-runtime-error.log" -Tail 100 -Wait

Remove Service¶

Stop-Service Bambuddy -Force -ErrorAction SilentlyContinue
C:\Bambuddy\nssm\nssm.exe remove Bambuddy confirm

Troubleshooting¶

Installer log is locked¶

If install.log is locked, close old PowerShell windows or previous installer sessions.

Then remove the old log if needed:

Remove-Item "C:\Bambuddy\install.log" -Force -ErrorAction SilentlyContinue

Runtime log is locked¶

If bambuddy-runtime.log shows repeated file lock errors, make sure the start script does not write directly to the same file that NSSM uses for stdout or stderr redirection.

Recommended setup:

• Start-Bambuddy.ps1 writes only to stdout
• NSSM redirects stdout to bambuddy-runtime.log
• NSSM redirects stderr to bambuddy-runtime-error.log

Service does not start¶

First test the start script manually:

powershell.exe -ExecutionPolicy Bypass -File "C:\Bambuddy\Start-Bambuddy.ps1"

If it works manually but not as a service, check the NSSM configuration:

C:\Bambuddy\nssm\nssm.exe edit Bambuddy

Also check:

C:\Bambuddy\bambuddy-runtime.log
C:\Bambuddy\bambuddy-runtime-error.log

Delete and recreate the service¶

Stop-Service Bambuddy -Force -ErrorAction SilentlyContinue
C:\Bambuddy\nssm\nssm.exe remove Bambuddy confirm

Then rerun the installer and register the service again.

Git clone fails¶

Check whether the installation directory is writable:

New-Item -Path "C:\Bambuddy\write-test.txt" -ItemType File -Force
Remove-Item "C:\Bambuddy\write-test.txt" -Force

If writing works but Git still fails, check antivirus or Windows Defender Controlled Folder Access:

Get-MpPreference | Select-Object EnableControlledFolderAccess

Port already in use¶

Choose another port:

.\windows-installer.ps1 -Port 8010

Or find the existing listener:

Get-NetTCPConnection -LocalPort 8000 -State Listen

Non-English Windows permissions¶

The installer avoids localized takeown prompts and uses icacls with SID-based permission grants instead.

Security Notes¶

• Run the installer only from a trusted source
• Review the PowerShell script before executing it
• Do not expose Bambuddy directly to the internet without protection
• Use a reverse proxy, VPN, or firewall rules for remote access
• Keep Git, Python, Bambuddy, and dependencies updated

Next Steps¶

After installation:

1. Open Bambuddy in your browser
2. Add your first printer
3. Check the runtime logs if anything does not start correctly
4. Register the Windows Service if Bambuddy should run permanently

Continue with First Printer Setup.