Skip to main content
BitBonsai is available as a Docker container template in Unraid Community Applications. This guide walks through installation, configuration, and GPU setup.

​
Prerequisites

  • Unraid 6.9+ (6.11+ recommended)
  • Community Applications plugin installed
  • Media library accessible on /mnt/user/ shares
  • (Optional) NVIDIA GPU with nvidia-driver plugin for hardware encoding

​
Install from Community Applications

1

Open Community Applications

Navigate to Apps tab in Unraid webUI.
2

Search for BitBonsai

Search for bitbonsai and select the template.
3

Review Configuration

The template includes pre-configured settings for both backend and frontend containers.
If BitBonsai is not yet available in Community Apps, use the manual Docker installation below.

​
Manual Docker Installation

​
Backend Container

1

Add Container

Go to Docker tab → Add Container.
2

Configure Repository

Repository: ghcr.io/bitbonsai/backend:latest
3

Set Network Mode

Network Type: bridge (recommended)
4

Configure Ports

Container PortHost PortDescription
31003100Backend API
54325432PostgreSQL database
5

Add Path Mappings

Container PathHost PathModeDescription
/config/mnt/user/appdata/bitbonsaiRead/WriteApp config and database
/videos/mnt/user/videosRead/WriteMedia libraries (adjust to your path)
6

Set Environment Variables

VariableValueDescription
POSTGRES_USERbitbonsaiDatabase username
POSTGRES_PASSWORDchangemeDatabase password (change this!)
POSTGRES_DBbitbonsaiDatabase name
NODE_ENVproductionRuntime environment
7

Apply and Start

Click Apply to create and start the container.

​
Frontend Container

1

Add Second Container

Go to Docker tab → Add Container.
2

Configure Repository

Repository: ghcr.io/bitbonsai/frontend:latest
3

Set Network Mode

Network Type: bridge
4

Configure Port

Container PortHost PortDescription
804210Web interface
5

Set Backend URL

VariableValueDescription
API_URLhttp://[UNRAID-IP]:3100Backend API endpoint
Replace [UNRAID-IP] with your server’s IP (e.g., http://192.168.1.100:3100).
6

Apply and Start

Click Apply to create and start the container.

​
Path Mapping for Media Libraries

Unraid uses /mnt/user/ paths for shares. BitBonsai must access the same physical path inside the container.

​
Example Configurations

ScenarioHost PathContainer Path
Single media share/mnt/user/media/videos
Multiple shares/mnt/user//mnt/user/ (passthrough)
Specific folders/mnt/user/media/movies/movies
Critical: When adding libraries in BitBonsai, use the container path (e.g., /videos/movies), NOT the Unraid host path.
Best Practice: Map /mnt/user/ → /mnt/user/ to avoid path translation issues. This allows BitBonsai to use identical paths to Unraid.

​
How to Verify Path Mapping

  1. Add a test library in BitBonsai using the container path
  2. Start a scan
  3. If files are not detected, check Docker logs: 
    docker logs bitbonsai-backend
  4. Look for errors like ENOENT: no such file or directory

​
Network Mode Selection

ModeProsConsRecommendation
BridgeIsolated, port controlManual port mapping✅ Recommended
HostNo port mapping neededExposes all portsUse only if needed
CustomAdvanced routingRequires network configAdvanced users only
Bridge mode is recommended for security. Frontend and backend communicate via host IP.

​
GPU Passthrough (Hardware Encoding)

BitBonsai supports NVIDIA GPU acceleration for faster encoding.

​
Requirements

  • NVIDIA GPU installed in Unraid server
  • nvidia-driver plugin installed from Community Apps
  • Container runtime configured for GPU access

​
Setup Steps

1

Install nvidia-driver Plugin

  1. Go to Apps → Search for nvidia-driver
  2. Install and configure for your GPU
  3. Reboot if prompted
2

Enable GPU in Backend Container

Edit the BitBonsai backend container:
  1. Extra Parameters: 
    --runtime=nvidia --gpus all
  2. Environment Variables: 
    NVIDIA_VISIBLE_DEVICES=all
NVIDIA_DRIVER_CAPABILITIES=all
3

Restart Container

Stop and start the backend container.
4

Verify GPU Access

Check container logs:
docker exec bitbonsai-backend nvidia-smi
Should display GPU information.
GPU encoding requires HEVC (h264_nvenc/hevc_nvenc) or AV1 (av1_nvenc) codec support. Check your GPU’s capabilities.
To verify FFmpeg sees the GPU:
docker exec bitbonsai-backend ffmpeg -encoders | grep nvenc

​
Starting the Containers

After configuration:
  1. Both containers should auto-start with Unraid
  2. Backend may take 30-60 seconds to initialize database
  3. Check Docker tab for status (green = running)

​
Verify Installation

  1. Backend health check: 
    curl http://[UNRAID-IP]:3100/health
    Should return: {"status":"ok"}
  2. Access Web UI: 
    http://[UNRAID-IP]:4210

​
Accessing the Web Interface

Open your browser and navigate to: 
http://[UNRAID-IP]:4210
Replace [UNRAID-IP] with your server’s IP address (e.g., http://192.168.1.100:4210).

​
First-Time Setup

  1. Click Add Library
  2. Enter container path (e.g., /videos/movies)
  3. Select codec (HEVC recommended)
  4. Click Scan Library

​
Troubleshooting Unraid-Specific Issues

​
Container Won’t Start

Symptom: Container immediately stops after starting. Solutions:
  1. Check Docker logs: 
    docker logs bitbonsai-backend
  2. Verify port conflicts (3100, 4210, 5432 not in use)
  3. Check appdata directory permissions: 
    ls -la /mnt/user/appdata/bitbonsai

​
“Permission Denied” Errors

Symptom: Cannot read/write video files. Solutions:
  1. Verify path mapping matches your Unraid shares
  2. Check container runs as correct user (usually nobody:users)
  3. Set permissions on media folder: 
    chmod -R 777 /mnt/user/videos
    (Adjust as needed for security)

​
Path Mapping Issues

Symptom: “No videos found” after scanning. Solutions:
  1. Verify container path matches host path mapping
  2. Use Console button in Docker tab to access container: 
    ls /videos
    Confirm files are visible inside container
  3. Check path in BitBonsai matches container path, not host path

​
Backend Cannot Connect to Database

Symptom: Backend logs show PostgreSQL connection errors. Solutions:
  1. Verify PostgreSQL port 5432 is not blocked
  2. Check POSTGRES_PASSWORD environment variable is set
  3. Delete /mnt/user/appdata/bitbonsai/postgres and restart (will recreate DB)

​
GPU Not Detected

Symptom: Encoding uses CPU instead of GPU. Solutions:
  1. Verify nvidia-driver plugin is running: 
    nvidia-smi
  2. Check container has GPU access: 
    docker exec bitbonsai-backend nvidia-smi
  3. Verify --runtime=nvidia in Extra Parameters
  4. Restart container after nvidia-driver updates

​
Frontend Shows “Cannot Connect to Backend”

Symptom: Web UI displays connection error. Solutions:
  1. Verify backend is running (Docker tab)
  2. Check API_URL environment variable in frontend container
  3. Test backend directly: 
    curl http://[UNRAID-IP]:3100/health
  4. Ensure no firewall blocking port 3100

​
Next Steps

Add Your First Library

Scan and encode your first video collection

Multi-Node Setup

Add worker nodes for faster encoding

Troubleshooting Guide

Fix common issues and optimize performance