vinez/bambuddy
1
0
Fork 0
mirror of https://github.com/maziggy/bambuddy.git synced 2026-08-11 00:30:12 -04:00
Code Issues Projects Releases Packages Wiki Activity Actions
bambuddy/install
History
Exact
maziggy 5bbfeefa65 fix(backup): diagnose an unwritable backup path instead of quoting errno 30 (#2544) 
Nightly backups to a mounted NAS share ran from May and then stopped, failing
with [Errno 30] Read-only file system. The reporter checked folder permissions
-- correctly: the mount is gid=backup,dir_mode=0775, the service user is in that
group, and his own shell writes to the share fine.

Errno 30 is EROFS. A permission problem is errno 13. EROFS means the filesystem
refused the write, and it refused because we told it to: our systemd unit ships
ProtectSystem=strict, which mounts everything read-only inside the service's
mount namespace and carves back out only ReadWritePaths=<install> <data> <logs>.
A NAS share is not one of those three. Reads are unaffected -- which is why the
UI happily listed his existing backups from the share while being unable to
write a new one -- and his shell is outside the namespace entirely, so every
check he could think to run said the directory was fine.

Both installers write the unit file wholesale, so a ReadWritePaths line added by
hand disappeared on the next install, taking the backups with it. They now back
the old unit up (.bak-<timestamp>) and carry the operator's extra writable paths
forward, reporting which ones they kept. The unit template documents the
carve-out.

The output directory is probed with a real write when it is saved and when the
backup card loads, so an unwritable path is caught there rather than at 03:00
for a week. On failure the card names the cause and hands over the fix with the
operator's path already in it (systemctl edit bambuddy -> ReadWritePaths=...),
and a failed run reports the same diagnosis rather than the raw OSError. EROFS
outside systemd, permission-denied, out-of-space, not-a-directory and missing are
told apart, in all 11 locales.

Docker: a backup path that is not bind-mounted is writable -- the write lands in
the container's ephemeral layer and is lost on the next compose up. The probe
compares the directory's device against the container root and warns, with the
compose snippet that mounts it properly.
2026-07-12 08:44:53 +02:00
..
docker-install.ps1 fix(virtual-printer): #1558 Send pre-flight + slicer-surface audit bundle 2026-05-30 13:34:10 +02:00
docker-install.sh fix(install): docker installer tries mkdir without sudo, escalates on EACCES (#1774) 2026-06-19 08:14:49 +02:00
install.sh fix(backup): diagnose an unwritable backup path instead of quoting errno 30 (#2544) 2026-07-12 08:44:53 +02:00
README.md docs(install): polish Windows section + Service/Update/Troubleshooting 2026-06-02 15:25:31 +02:00
update.sh Added new update.sh and update docs 2026-04-19 09:08:30 +02:00
update_macos.sh Added install/update_macos.sh 2026-03-31 10:25:57 +02:00

README.md

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