Installation¶

This guide covers all methods for installing Bambuddy on your system.

Requirements¶

Before you begin, ensure you have:

Quick Install¶

# Install prerequisites (if needed)
brew install python@3.12

# Clone and setup
git clone https://github.com/maziggy/bambuddy.git
cd bambuddy
python3 -m venv venv
source venv/bin/activate
pip install -r requirements.txt

# Run
uvicorn backend.app.main:app --host 0.0.0.0 --port 8000

# Install prerequisites
sudo apt update
sudo apt install python3 python3-venv python3-pip git

# Clone and setup
git clone https://github.com/maziggy/bambuddy.git
cd bambuddy
python3 -m venv venv
source venv/bin/activate
pip install -r requirements.txt

# Run
uvicorn backend.app.main:app --host 0.0.0.0 --port 8000

# Clone and setup
git clone https://github.com/maziggy/bambuddy.git
cd bambuddy
python -m venv venv
.\venv\Scripts\Activate.ps1
pip install -r requirements.txt

# Run
uvicorn backend.app.main:app --host 0.0.0.0 --port 8000

Open http://localhost:8000 in your browser.

Running as a Service¶

For production use, run Bambuddy as a system service that starts automatically.

sudo nano /etc/systemd/system/bambuddy.service

[Unit]
Description=BamBuddy Print Archive
After=network.target

[Service]
Type=simple
User=YOUR_USERNAME
Group=YOUR_USERNAME
WorkingDirectory=/home/YOUR_USERNAME/bambuddy
Environment="PATH=/home/YOUR_USERNAME/bambuddy/venv/bin"

# Kill any zombie ffmpeg processes before starting/after stopping
# The - prefix ignores errors if no ffmpeg processes exist
ExecStartPre=-/usr/bin/pkill -9 ffmpeg
ExecStopPost=-/usr/bin/pkill -9 ffmpeg

# Ensure directories exist and have correct permissions
# The + prefix runs the command as root even though User= is set
ExecStartPre=+/bin/mkdir -p /home/YOUR_USERNAME/bambuddy/logs
ExecStartPre=+/bin/mkdir -p /home/YOUR_USERNAME/bambuddy/archive
ExecStartPre=+/bin/chown -R YOUR_USERNAME:YOUR_USERNAME /home/YOUR_USERNAME/bambuddy/logs
ExecStartPre=+/bin/chown -R YOUR_USERNAME:YOUR_USERNAME /home/YOUR_USERNAME/bambuddy/archive

ExecStart=/home/YOUR_USERNAME/bambuddy/venv/bin/uvicorn backend.app.main:app --host 0.0.0.0 --port 8000
Restart=always
RestartSec=10

[Install]
WantedBy=multi-user.target

sudo systemctl daemon-reload
sudo systemctl enable bambuddy
sudo systemctl start bambuddy

sudo systemctl status bambuddy

sudo journalctl -u bambuddy -f

nano ~/Library/LaunchAgents/com.bambuddy.plist

<?xml version="1.0" encoding="UTF-8"?>
<!DOCTYPE plist PUBLIC "-//Apple//DTD PLIST 1.0//EN" "http://www.apple.com/DTDs/PropertyList-1.0.dtd">
<plist version="1.0">
<dict>
    <key>Label</key>
    <string>com.bambuddy</string>
    <key>ProgramArguments</key>
    <array>
        <string>/Users/YOUR_USERNAME/bambuddy/venv/bin/uvicorn</string>
        <string>backend.app.main:app</string>
        <string>--host</string>
        <string>0.0.0.0</string>
        <string>--port</string>
        <string>8000</string>
    </array>
    <key>WorkingDirectory</key>
    <string>/Users/YOUR_USERNAME/bambuddy</string>
    <key>RunAtLoad</key>
    <true/>
    <key>KeepAlive</key>
    <true/>
</dict>
</plist>

launchctl load ~/Library/LaunchAgents/com.bambuddy.plist

Configuration¶

Configure Bambuddy using environment variables or a .env file:

cp .env.example .env
nano .env

Environment Variables¶

Production Settings (default)¶

• INFO level logging
• SQLAlchemy and HTTP library noise suppressed
• Logs written to logs/bambuddy.log (5MB rotating, 3 backups)

Development Settings¶

For debugging, create a .env file:

DEBUG=true
LOG_TO_FILE=true

This enables:

• DEBUG level logging (very verbose)
• All SQL queries logged
• Useful for troubleshooting printer connections

Network Requirements¶

Ensure your firewall allows these connections:

Updating¶

Manual Update¶

cd bambuddy
git pull origin main
source venv/bin/activate
pip install -r requirements.txt

Then restart the service:

sudo systemctl restart bambuddy  # Linux

Auto Updates¶

Bambuddy includes automatic update checking. Go to Settings to check for updates and apply them with one click.

Build Frontend from Source¶

The repository includes pre-built frontend files. To build from source:

# Install Node.js 18+ first
cd frontend
npm install
npm run build
cd ..

Next Steps¶

Now that Bambuddy is installed: