maziggy
0dfcff5925
asyncio's Server has a __dict__ and uvloop's, a Cython cdef class, does not, so the attribute added in 1.2.5.4 raised AttributeError under uvloop. Every RTSP camera failed before opening a socket, which is the diagnostic's capture_exception at 0 ms. Our own unit files all pin --loop asyncio for #1896 and were never affected. The reports come from units we do not write: the Proxmox VE Helper-Scripts LXC pins no loop, and installs predating that fix never gained the flag because update.sh does not rewrite unit files. The loop is not ours to assume, so fix the code rather than add another flag. The set moves to a module-level WeakKeyDictionary, keyed weakly so an abandoned proxy retires its own entry rather than leaking one and later handing a new server a dead one's handlers. Pinned on a real uvloop loop and, for hosts without uvloop, against a __slots__ server; conftest builds its loop from the default policy, so nothing in the suite had ever run the branch that broke. Also routes the two external-camera teardowns through close_tls_proxy, which #2968 introduced and left them out of. ----- Say so at startup when running on uvloop (issue #3001) An install on the wrong loop had no way to find out it was. #3001 was loud enough to notice; the #1896 upload truncation it is also exposed to is silent, and shows up as a print failing from a file that was corrupt on arrival. One WARNING in the lifespan naming the loop, the risk and the flag to add. A warning and not a refusal: uvicorn has already chosen its loop by the time any application code runs, and a server that answers requests beats one that will not boot. Asks the running loop what it is rather than whether uvloop imports -- uvicorn[standard] installs uvloop everywhere, so its presence says nothing -- and matches on the module name so the question never imports uvloop on a host without it. ----- Repair a service file written before the --loop asyncio pin (issue #3001) install.sh has pinned the loop since #1896, but nothing has ever rewritten an existing service file, so every native install created between 2025-11-28 (when uvicorn[standard] brought uvloop into the venv) and 2026-07-05 still runs on uvloop no matter how often it is updated. Both update scripts now add the flag themselves while the service is stopped, so it takes effect on the same restart -- systemd via sed, launchd via PlistBuddy, each backing the file up first and inserting nothing but the flag. Refuses to edit and explains instead when the shape is not a plain single-line uvicorn unit: a wrapper script, a continued ExecStart, several of them, a read-only file, or a service with drop-ins, since a drop-in may be what defines ExecStart and editing the fragment would change nothing while reporting success. A deliberate --loop uvloop is left alone. Reads the effective ExecStart from systemd rather than the file, so it is idempotent.
BamBuddy Installation Scripts
Interactive installation scripts for BamBuddy with support for both native and Docker deployments.
Quick Start
Docker Installation (Recommended)
Linux/macOS:
curl -fsSL https://raw.githubusercontent.com/maziggy/bambuddy/main/install/docker-install.sh -o docker-install.sh && chmod +x docker-install.sh && ./docker-install.sh
Windows (Command Prompt or PowerShell):
powershell -ExecutionPolicy Bypass -Command "iwr -useb https://raw.githubusercontent.com/maziggy/bambuddy/main/install/docker-install.ps1 -OutFile docker-install.ps1; .\docker-install.ps1"
Requires Docker Desktop running. Printer auto-discovery is unavailable in Docker Desktop — add printers manually by IP.
Native Installation
Linux/macOS:
curl -fsSL https://raw.githubusercontent.com/maziggy/bambuddy/main/install/install.sh -o install.sh && chmod +x install.sh && ./install.sh
Windows Native Installation
Windows PowerShell:
powershell -ExecutionPolicy Bypass -Command "iwr -useb https://raw.githubusercontent.com/maziggy/bambuddy/main/install/windows-installer.ps1 -OutFile windows-installer.ps1; .\windows-installer.ps1"
Unattended:
.\windows-installer.ps1 -InstallDir C:\Bambuddy -Port 8000 -Yes
Scripts Overview
| Script | Platform | Method |
|---|---|---|
install.sh |
Linux, macOS | Native (Python venv) |
docker-install.sh |
Linux, macOS | Docker |
docker-install.ps1 |
Windows (Docker Desktop) | Docker |
windows-installer.ps1 |
Windows (Native) | Windows Service |
update.sh |
Linux (systemd) | Native update helper |
Native Installation Scripts
install.sh (Linux/macOS)
Installs BamBuddy with Python virtual environment and optional systemd/launchd service.
Supported Systems:
- Debian/Ubuntu (apt)
- RHEL/Fedora/CentOS (dnf/yum)
- Arch Linux (pacman)
- openSUSE (zypper)
- macOS (Homebrew)
Options:
--path PATH Installation directory (default: /opt/bambuddy)
--port PORT Port to listen on (default: 8000)
--tz TIMEZONE Timezone (default: system timezone)
--data-dir PATH Data directory (default: INSTALL_PATH/data)
--log-dir PATH Log directory (default: INSTALL_PATH/logs)
--debug Enable debug mode
--log-level LEVEL Log level: DEBUG, INFO, WARNING, ERROR (default: INFO)
--no-service Skip systemd/launchd service setup
--yes, -y Non-interactive mode, accept defaults
Examples:
# Interactive installation
./install.sh
# Unattended with custom settings
./install.sh --path /srv/bambuddy --port 3000 --tz America/New_York --yes
# Minimal unattended
./install.sh -y
# Skip service setup
./install.sh --no-service -y
windows-installer.ps1 (Windows)
Windows PowerShell (run as Administrator — the installer self-elevates via UAC if not):
powershell -ExecutionPolicy Bypass -Command "iwr -useb https://raw.githubusercontent.com/maziggy/bambuddy/main/install/windows-installer.ps1 -OutFile windows-installer.ps1; .\windows-installer.ps1"
Installs Bambuddy natively on Windows using Git, Python, a virtual environment, and optional NSSM Windows Service registration. See the Windows Installer Guide for full parameter reference.
Parameters:
-InstallDir PATH Installation directory (default: C:\Bambuddy)
-Port PORT Port to listen on (default: 8000)
-Yes Non-interactive mode, accept defaults
-Silent Non-interactive mode with reduced console output
-NoService Skip Windows Service setup
-NoStart Do not start Bambuddy at the end
-LocalOnly Bind to 127.0.0.1 instead of all LAN interfaces
The installer stores the Git checkout in INSTALL_DIR\bambuddy, user data in
INSTALL_DIR\data, and application logs in INSTALL_DIR\logs so updates and
re-clones do not delete runtime data. If an earlier Windows installer run left
runtime data in the Git checkout, the installer moves known data and log paths
to the new locations before starting Bambuddy.
Docker Installation Scripts
docker-install.sh (Linux/macOS)
Installs BamBuddy using Docker containers.
Options:
--path PATH Installation directory (default: ~/bambuddy)
--port PORT Port to expose (default: 8000)
--tz TIMEZONE Timezone (default: system timezone)
--build Build from source instead of using pre-built image
--yes, -y Non-interactive mode, accept defaults
Examples:
# Interactive installation
./docker-install.sh
# Unattended with custom settings
./docker-install.sh --path /srv/bambuddy --port 3000 --tz Europe/Berlin --yes
# Build from source
./docker-install.sh --build --yes
docker-install.ps1 (Windows)
PowerShell mirror of docker-install.sh for Windows + Docker Desktop. Verifies
Docker Desktop is running, downloads docker-compose.yml, rewrites it to use
port mappings instead of host networking (Docker Desktop doesn't support host
networking), and starts the container.
Requirements:
- Docker Desktop installed and running (download)
- PowerShell 5.1+ (ships with Windows 10/11) or PowerShell 7+
Parameters:
-InstallPath PATH Installation directory (default: %USERPROFILE%\bambuddy)
-Port PORT Port to expose (default: 8000)
-TimeZone TZ IANA timezone (default: derived from Get-TimeZone or UTC)
-Build Build from source instead of pulling pre-built image
-Yes Non-interactive mode, accept defaults
-Help Show full help (Get-Help)
Examples:
# Interactive
.\docker-install.ps1
# Unattended
.\docker-install.ps1 -InstallPath C:\bambuddy -Port 8080 -TimeZone Europe/Berlin -Yes
# Build from source
.\docker-install.ps1 -Build -Yes
Limitations on Windows / Docker Desktop: Printer auto-discovery (SSDP) does not work — add printers manually by IP. The Virtual Printer feature requires manually uncommenting the relevant port mappings in
docker-compose.yml(the script leaves them commented because most users don't need them).
Configuration Options
All scripts support these configuration options:
| Option | Description | Default |
|---|---|---|
| Install Path | Where BamBuddy is installed | /opt/bambuddy (Linux/Docker) |
| Port | HTTP port for web interface | 8000 |
| Timezone | Server timezone | System timezone or UTC |
| Data Directory | Database and archives | INSTALL_PATH/data |
| Log Directory | Application logs | INSTALL_PATH/logs |
| Debug Mode | Enable verbose logging | false |
| Log Level | INFO, WARNING, ERROR, DEBUG | INFO |
Post-Installation
Accessing BamBuddy
After installation, open your browser to:
http://localhost:8000
Or use the port you specified during installation.
Service Management
Linux (systemd):
sudo systemctl status bambuddy # Check status
sudo systemctl start bambuddy # Start
sudo systemctl stop bambuddy # Stop
sudo systemctl restart bambuddy # Restart
sudo journalctl -u bambuddy -f # View logs
macOS (launchd):
launchctl list | grep bambuddy # Check status
launchctl load ~/Library/LaunchAgents/com.bambuddy.app.plist # Start
launchctl unload ~/Library/LaunchAgents/com.bambuddy.app.plist # Stop
Windows (NSSM service):
Get-Service Bambuddy # Check status
Start-Service Bambuddy # Start
Stop-Service Bambuddy # Stop
Restart-Service Bambuddy # Restart
Get-Content "C:\Bambuddy\bambuddy-runtime.log" -Tail 100 -Wait # View logs
Docker:
docker compose ps # Check status
docker compose up -d # Start
docker compose down # Stop
docker compose restart # Restart
docker compose logs -f # View logs
Updating
Native installation:
curl -fsSL https://raw.githubusercontent.com/maziggy/bambuddy/main/install/update.sh -o update.sh
chmod +x update.sh
sudo ./update.sh
The updater performs:
- Root permission check (fails fast before any work)
- Optional built-in backup API call (
/api/v1/settings/backup) before update - Keeps only the newest 5 local backup ZIP files
- Local-change warning + confirmation before
git reset --hard - If remote has no new commits, updater exits early without stopping the service
- Service stop/start with code rollback + service restart attempt if update fails
Useful environment overrides:
# Typical native install defaults
INSTALL_DIR=/opt/bambuddy SERVICE_NAME=bambuddy sudo ./update.sh
# Require backup to succeed (abort update if backup fails)
BACKUP_MODE=require sudo ./update.sh
# Skip backup API call
BACKUP_MODE=skip sudo ./update.sh
# Auth-enabled instances: provide API key for backup endpoint
BAMBUDDY_API_KEY=bb_xxx BACKUP_MODE=require sudo ./update.sh
Docker (pre-built image):
cd ~/bambuddy
docker compose pull
docker compose up -d
Docker (from source):
cd ~/bambuddy
git pull
docker compose up -d --build
Windows (native): rerun the installer; it detects the existing checkout and offers git pull, leaving INSTALL_DIR\data and INSTALL_DIR\logs untouched. Stop the service first if it is registered:
Stop-Service Bambuddy
.\windows-installer.ps1 -Yes
Start-Service Bambuddy
Troubleshooting
Permission Denied (Linux)
Run with sudo or ensure your user has appropriate permissions:
sudo ./install.sh
Docker: Printer Discovery Not Working
Docker Desktop for macOS doesn't support host networking. Add printers manually by IP address in the BamBuddy web interface.
Service Won't Start
Check logs for errors:
# Linux
sudo journalctl -u bambuddy -n 50
# Docker
docker compose logs bambuddy
Port Already in Use
Choose a different port during installation or stop the conflicting service:
# Find what's using port 8000
sudo lsof -i :8000 # Linux/macOS
# Windows
Get-NetTCPConnection -LocalPort 8000 -State Listen
Windows: Service Won't Start
Test the start script manually first:
powershell.exe -ExecutionPolicy Bypass -File "C:\Bambuddy\Start-Bambuddy.ps1"
Then check the NSSM runtime logs:
Get-Content "C:\Bambuddy\bambuddy-runtime-error.log" -Tail 100
Requirements
Native Installation
- Python 3.10+ (automatically installed if missing)
- Node.js 18+ (automatically installed if missing)
- Git (automatically installed if missing)
- ~500MB disk space
Docker Installation
- Docker Engine 20+ or Docker Desktop
- ~1GB disk space (includes image)
Support
- Documentation: https://wiki.bambuddy.cool
- Discord: https://discord.gg/aFS3ZfScHM
- Issues: https://github.com/maziggy/bambuddy/issues