Installation¶

Get Bambuddy running in about a minute. One command, one browser tab — you're done.

Quick Install (Recommended)¶

The easiest way to install Bambuddy. Interactive scripts that handle everything for you.

curl -fsSL https://raw.githubusercontent.com/maziggy/bambuddy/main/install/install.sh -o install.sh && chmod +x install.sh && ./install.sh

curl -fsSL https://raw.githubusercontent.com/maziggy/bambuddy/main/install/install.sh -o install.sh && chmod +x install.sh && ./install.sh

The script will:

• Prompt for install path, port, bind address, timezone, and more
• Detect your package manager and install dependencies
• Set up Python virtual environment
• Build the frontend (Node.js 22)
• Create a systemd/launchd service
• Start Bambuddy automatically

curl -fsSL https://raw.githubusercontent.com/maziggy/bambuddy/main/install/install.sh | bash -s -- --yes

curl -fsSL https://raw.githubusercontent.com/maziggy/bambuddy/main/install/install.sh | bash -s -- --path /srv/bambuddy --port 3000 --yes

Requirements¶

Before you begin, make sure you have:

Manual Install¶

Prefer to do it yourself? Follow these steps.

# 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

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:

Reverse Proxy¶

Bambuddy serves plain HTTP on port 8000. Put a reverse proxy in front of it to add HTTPS, a friendly hostname, or to expose it over the internet. This applies equally to the quick-install, manual, and Docker deployments — only the upstream target changes (localhost:8000 for host installs, the container name for Docker Compose).

Nginx¶

server {
    listen 443 ssl http2;
    server_name bambuddy.yourdomain.com;

    ssl_certificate /path/to/cert.pem;
    ssl_certificate_key /path/to/key.pem;

    location / {
        proxy_pass http://localhost:8000;
        proxy_http_version 1.1;
        proxy_set_header Upgrade $http_upgrade;
        proxy_set_header Connection "upgrade";
        proxy_set_header Host $host;
        proxy_set_header X-Real-IP $remote_addr;
        proxy_set_header X-Forwarded-For $proxy_add_x_forwarded_for;
        proxy_set_header X-Forwarded-Proto $scheme;

        # WebSocket / long poll timeout
        proxy_read_timeout 86400;
    }
}

Caddy¶

Caddy is a simpler alternative with automatic HTTPS via Let's Encrypt. WebSockets and the correct forwarding headers (X-Forwarded-For, X-Forwarded-Proto, Host) work out of the box — no extra directives required.

bambuddy.yourdomain.com {
    reverse_proxy localhost:8000
}

bambuddy.local {
    reverse_proxy localhost:8000
    tls internal
}

services:
  caddy:
    image: caddy:2
    restart: unless-stopped
    ports:
      - "80:80"
      - "443:443"
    volumes:
      - ./Caddyfile:/etc/caddy/Caddyfile:ro
      - caddy_data:/data
      - caddy_config:/config
    networks:
      - bambuddy_net

volumes:
  caddy_data:
  caddy_config:

bambuddy.yourdomain.com {
    reverse_proxy bambuddy:8000
}

After editing the Caddyfile, reload without downtime:

sudo systemctl reload caddy
# or, in Docker:
docker compose exec caddy caddy reload --config /etc/caddy/Caddyfile

Updating¶

Recommended: update.sh¶

sudo /opt/bambuddy/install/update.sh

update.sh stops the service, snapshots the database via the built-in backup API, fast-forwards to origin/main, installs Python dependencies, rebuilds the frontend, and restarts the service. It rolls back automatically if any step fails.

Manual update¶

If you prefer to run the steps yourself:

cd /opt/bambuddy
sudo systemctl stop bambuddy
sudo -u bambuddy git fetch origin
sudo -u bambuddy git reset --hard origin/main
sudo -u bambuddy venv/bin/pip install -r requirements.txt
sudo systemctl start bambuddy

Replace /opt/bambuddy with your install directory if different. Database schema migrations run automatically on startup.

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: