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

3

Set Network Mode

Network Type: bridge (recommended)
4

Configure Ports

5

Add Path Mappings

6

Set Environment Variables

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

3

Set Network Mode

Network Type: bridge
4

Configure Port

5

Set Backend URL

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

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:
  4. Look for errors like ENOENT: no such file or directory

​
Network Mode Selection

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:
  2. Environment Variables:
3

Restart Container

Stop and start the backend container.
4

Verify GPU Access

Check container logs:
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:

​
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:
    Should return: {"status":"ok"}
  2. Access Web UI:

​
Accessing the Web Interface

Open your browser and navigate to:
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:
  2. Verify port conflicts (3100, 4210, 5432 not in use)
  3. Check appdata directory permissions:

​
“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:
    (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:
    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:
  2. Check container has GPU access:
  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:
  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