Docker Installation¶

Docker is the easiest way to run Bambuddy. One command and you're done!

Quick Start¶

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

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

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

mkdir bambuddy && cd bambuddy
curl -O https://raw.githubusercontent.com/maziggy/bambuddy/main/docker-compose.yml
docker compose up -d

git clone https://github.com/maziggy/bambuddy.git
cd bambuddy
docker compose up -d --build

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

Configuration¶

docker-compose.yml¶

The default docker-compose.yml works out of the box:

services:
  bambuddy:
    image: ghcr.io/maziggy/bambuddy:latest
    build: .
    # Usage:
    #   docker compose up -d          → pulls pre-built image
    #   docker compose up -d --build  → builds from source
    container_name: bambuddy
    network_mode: host  # Required for printer discovery
    volumes:
      - bambuddy_data:/app/data
      - bambuddy_logs:/app/logs
    environment:
      - TZ=Europe/Berlin  # Your timezone
    restart: unless-stopped

volumes:
  bambuddy_data:
  bambuddy_logs:

Environment Variables¶

Custom Port¶

PORT=8080 docker compose up -d

environment:
  - TZ=Europe/Berlin
  - PORT=8080

ports:
  - "8080:8000"  # Access on port 8080

Data Persistence¶

Three volumes store your data:

Updating¶

docker compose pull
docker compose up -d

docker compose pull && docker compose up -d

cd bambuddy
git pull
docker compose build --pull
docker compose up -d

cd bambuddy && git pull && docker compose build --pull && docker compose up -d

Useful Commands¶

View Logs¶

# Follow logs
docker compose logs -f

# Last 100 lines
docker compose logs --tail 100

Stop/Start¶

# Stop
docker compose down

# Start
docker compose up -d

Rebuild (after changes)¶

docker compose up -d --build

Shell Access¶

docker compose exec bambuddy /bin/bash

Advanced Setups¶

Reverse Proxy (Nginx)¶

To run Bambuddy behind a reverse proxy with HTTPS:

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 support
        proxy_read_timeout 86400;
    }
}

Traefik Labels¶

If you're using Traefik:

services:
  bambuddy:
    build: .
    labels:
      - "traefik.enable=true"
      - "traefik.http.routers.bambuddy.rule=Host(`bambuddy.yourdomain.com`)"
      - "traefik.http.routers.bambuddy.entrypoints=websecure"
      - "traefik.http.routers.bambuddy.tls.certresolver=letsencrypt"
    # ... rest of config

Network Mode Host¶

Host network mode is required for printer discovery and camera streaming:

services:
  bambuddy:
    build: .
    network_mode: host
    # Note: ports mapping not needed with host mode

macOS and Windows (Docker Desktop)¶

Docker Desktop on macOS and Windows runs containers inside a Linux VM, so network_mode: host connects to the VM's network, not your computer's network. This means:

• Port 8000 won't be accessible via localhost
• Printer discovery won't work (the container can't see your LAN)

Solution: Use port mapping instead of host mode:

services:
  bambuddy:
    image: ghcr.io/maziggy/bambuddy:latest
    container_name: bambuddy
    # network_mode: host  # Doesn't work on macOS/Windows
    ports:
      - "${PORT:-8000}:8000"           # Use PORT=8080 docker compose up for custom port
      - "8883:8883"                    # Virtual printer MQTT (proxy mode)
      - "9990:9990"                    # Virtual printer FTP control
      - "50000-50100:50000-50100"      # Virtual printer FTP passive data
    volumes:
      - bambuddy_data:/app/data
      - bambuddy_logs:/app/logs
      - bambuddy_vprinter:/app/virtual_printer
    environment:
      - TZ=Europe/Berlin
    restart: unless-stopped

volumes:
  bambuddy_data:
  bambuddy_logs:
  bambuddy_vprinter:

Printer Discovery in Docker¶

When running in Docker with network_mode: host, Bambuddy uses subnet scanning instead of SSDP multicast for printer discovery:

1. Click Add Printer on the Printers page
2. Bambuddy detects it's running in Docker and shows a subnet input field
3. Enter your network range (e.g., 192.168.1.0/24)
4. Click Scan Network - Bambuddy will probe each IP for Bambu printer ports (8883, 990)
5. Discovered printers appear in the list with their name and model

Troubleshooting¶

Container Won't Start¶

Check the logs:

docker compose logs bambuddy

Common issues:

• Port in use: Change the port mapping
• Permission denied: Check volume permissions

Can't Connect to Printer¶

Ensure your Docker network can reach your printer:

# Test connectivity from inside container
docker compose exec bambuddy ping YOUR_PRINTER_IP

If using bridge network mode and having issues, try network_mode: host.

Database Issues¶

If you need to reset the database:

docker compose down
rm bambuddy.db
docker compose up -d

Next Steps¶