Bambuddy Deployment and Usage Guide

1. Prerequisites

Runtime & Tools

Node.js (v18 or later) - JavaScript runtime
npm or yarn - Package manager (npm comes with Node.js)
Git - Version control
Docker (optional) - For containerized deployment
Bambu Lab 3D Printer with Developer Mode enabled (required for local network control)
Network Access to your printer(s) via local network

Accounts (Optional)

Bambu Lab Cloud Account - For accessing cloud-based filament presets (optional, fallbacks included)
Home Assistant/Tasmota/MQTT - For smart plug integration (optional)
Tailscale/WireGuard - Recommended for secure remote Proxy Mode operation

2. Installation

Clone the Repository

# Clone the repository
git clone https://github.com/maziggy/bambuddy.git
cd bambuddy

# Install dependencies
npm install

Database Setup

Bambuddy uses SQLite by default (no additional setup required). For production, you can configure PostgreSQL:

# Install PostgreSQL (Ubuntu/Debian)
sudo apt-get install postgresql postgresql-contrib

# Create database and user
sudo -u postgres psql
CREATE DATABASE bambuddy;
CREATE USER bambuddy_user WITH ENCRYPTED PASSWORD 'your_password';
GRANT ALL PRIVILEGES ON DATABASE bambuddy TO bambuddy_user;

3. Configuration

Environment Variables

Create a .env file in the project root:

# Server Configuration
NODE_ENV=production
PORT=3000
HOST=0.0.0.0

# Database (SQLite default)
DATABASE_URL=file:./data/bambuddy.db

# For PostgreSQL:
# DATABASE_URL=postgresql://bambuddy_user:your_password@localhost:5432/bambuddy

# Printer Configuration
PRINTER_ACCESS_CODE=your_printer_access_code
PRINTER_LOCAL_IP=192.168.1.100

# Security
SESSION_SECRET=generate_a_secure_random_string_here
JWT_SECRET=another_secure_random_string

# Optional Features
ENABLE_PROXY_MODE=false  # Set to true for remote printing
CLOUD_FILAMENT_SYNC=true  # Set to false to use local presets only
EXTERNAL_CAMERA_URL=http://your-camera-ip:8080/?action=stream

# Smart Plug Integration (optional)
SMART_PLUG_TYPE=tasmota  # tasmota, homeassistant, or mqtt
SMART_PLUG_IP=192.168.1.50
MQTT_BROKER_URL=mqtt://localhost:1883

Printer Setup

Enable Developer Mode on your Bambu Lab printer:
- Go to Settings > General > About
- Tap the device model 5 times
- Enable "Developer Mode"
Get your Access Code:
- In Developer Mode, find "Access Code"
- Use this code in the PRINTER_ACCESS_CODE environment variable
Configure Local IP:
- Find your printer's IP address in the network settings
- Use this IP in PRINTER_LOCAL_IP

Proxy Mode Configuration (Remote Printing)

For secure remote printing via Proxy Mode:

ENABLE_PROXY_MODE=true
PROXY_TLS_ENABLED=true
PROXY_MQTT_PORT=8883
PROXY_FTP_PORT=990

# Recommended: Use VPN for full encryption
TAILSCALE_ENABLED=true

See the Proxy Mode documentation for detailed setup.

4. Build & Run

Development Mode

# Start development server with hot reload
npm run dev

# The application will be available at http://localhost:3000

Production Build

# Build the frontend and backend
npm run build

# Start production server
npm start

# Or use PM2 for process management
npm install -g pm2
pm2 start npm --name "bambuddy" -- start

Database Migrations

# Run database migrations
npx prisma migrate deploy

# Generate Prisma client
npx prisma generate

5. Deployment

Docker Deployment (Recommended)

# Build Docker image
docker build -t bambuddy .

# Run with environment variables
docker run -d \
  --name bambuddy \
  -p 3000:3000 \
  -v ./data:/app/data \
  -v ./uploads:/app/uploads \
  --env-file .env \
  bambuddy

Docker Compose

Create docker-compose.yml:

version: '3.8'
services:
  bambuddy:
    image: ghcr.io/maziggy/bambuddy:latest
    container_name: bambuddy
    restart: unless-stopped
    ports:
      - "3000:3000"
    volumes:
      - ./data:/app/data
      - ./uploads:/app/uploads
    environment:
      - NODE_ENV=production
      - DATABASE_URL=file:/app/data/bambuddy.db
      - PRINTER_ACCESS_CODE=${PRINTER_ACCESS_CODE}
      - PRINTER_LOCAL_IP=${PRINTER_LOCAL_IP}
      - SESSION_SECRET=${SESSION_SECRET}

Platform Recommendations

For Home/NAS Deployment:

Docker on Synology NAS, QNAP, or Unraid
Portainer for web-based Docker management
Raspberry Pi 4 (4GB+) for low-power operation

For Cloud Deployment:

Fly.io or Railway - Easy Node.js deployment
DigitalOcean App Platform - Managed app hosting
AWS ECS/EKS or Google Cloud Run - Scalable container hosting

For Advanced Users:

Kubernetes with Helm chart (community contribution needed)
Nomad for container orchestration

Reverse Proxy Setup (Production)

Use Nginx or Caddy as a reverse proxy:

# Nginx configuration
server {
    listen 80;
    server_name bambuddy.yourdomain.com;
    
    location / {
        proxy_pass http://localhost:3000;
        proxy_http_version 1.1;
        proxy_set_header Upgrade $http_upgrade;
        proxy_set_header Connection 'upgrade';
        proxy_set_header Host $host;
        proxy_cache_bypass $http_upgrade;
    }
}

6. Troubleshooting

Common Issues

1. Printer Connection Failed

Error: Unable to connect to printer

Verify Developer Mode is enabled on the printer
Check that PRINTER_ACCESS_CODE is correct
Ensure printer and server are on the same network
Test connectivity: ping <printer_ip>

2. Database Migration Errors

# Reset database (development only)
npx prisma migrate reset

# Check database connection
npx prisma db pull

3. WebSocket Connection Issues

Check firewall settings (port 3000 must be open)
Verify WebSocket support in reverse proxy configuration
Check browser console for WebSocket errors

4. Proxy Mode Not Working

Ensure ENABLE_PROXY_MODE=true is set
Verify ports 8883 (MQTT) and 990 (FTP) are forwarded
Check VPN connection if using Tailscale/WireGuard
Review Proxy Mode documentation

5. Filament Presets Not Loading

Check network connectivity to Bambu Cloud
Verify CLOUD_FILAMENT_SYNC setting
Fallback presets are always available (see frontend/src/components/spool-form/utils.ts)

6. Build Plate Empty Detection Issues

Ensure camera is properly configured
Check lighting conditions
Adjust ROI (Region of Interest) in settings
Run multi-reference calibration

Logs and Debugging

# View application logs
npm run logs

# Docker logs
docker logs bambuddy

# Enable debug mode
DEBUG=* npm start

# Check WebSocket connections
# Monitor browser console for WebSocket messages

Getting Help

Discord Community: Join Discord
Documentation: Wiki
GitHub Issues: Report Issues
Ko-fi Support: Support Development

Performance Tips

Use SSD storage for database and uploads
Enable gzip compression in reverse proxy
Set appropriate max_old_space_size for Node.js memory limits
Regularly prune old print data if storage is limited
Use separate volumes for database and uploads in Docker

How to Deploy & Use bambuddy