System Requirements

Minimum Requirements

Basic Setup

Suitable for small libraries (< 500 videos) on a single node

Component	Minimum Spec
CPU	4 cores (x86_64 or ARM64)
RAM	4 GB
Storage	20 GB (system) + video library space
OS	Linux, Windows (with WSL2), macOS
Software	Docker 20.10+, Docker Compose 2.0+

Recommended Specifications

Medium Library

1,000-5,000 videos

8+ cores
8 GB RAM
Hardware transcoding (optional)

Large Library

5,000+ videos

16+ cores (or multi-node setup)
16 GB RAM
NFS storage for multi-node

Performance Factors

Factor	Impact	Recommendation
CPU Cores	Encoding speed	More cores = faster encoding
RAM	Job concurrency	4 GB + (2 GB per concurrent job)
Storage	Temp files during encoding	SSD recommended for temp directory
Network	Multi-node performance	1 Gbps+ for NFS shared storage

Software Requirements

Docker & Docker Compose

Linux
Windows (WSL2)
macOS

# Install Docker
curl -fsSL https://get.docker.com | sh

# Install Docker Compose
sudo apt install docker-compose-plugin

# Verify versions
docker --version          # Should be 20.10+
docker compose version    # Should be 2.0+

# Install Docker Desktop with WSL2 backend
# Download from: https://www.docker.com/products/docker-desktop

# Enable WSL2
wsl --install

# Verify in WSL2 terminal
docker --version
docker compose version

# Install Docker Desktop
# Download from: https://www.docker.com/products/docker-desktop

# Or use Homebrew
brew install --cask docker

# Verify
docker --version
docker compose version

Hardware Transcoding (Optional)

Hardware encoding is 5-10x faster than software encoding but may reduce quality slightly.

Supported GPUs

NVIDIA

NVENCGTX 1050+ or RTX seriesRequires NVIDIA drivers

Intel

Quick Sync (QSV)6th gen (Skylake) or newerBuilt into CPU

AMD

VCE/VCNRX 400 series or newerLimited support

Docker GPU Passthrough

NVIDIA Setup:

# Install NVIDIA Container Toolkit
distribution=$(. /etc/os-release;echo $ID$VERSION_ID)
curl -s -L https://nvidia.github.io/nvidia-docker/gpgkey | sudo apt-key add -
curl -s -L https://nvidia.github.io/nvidia-docker/$distribution/nvidia-docker.list | \
  sudo tee /etc/apt/sources.list.d/nvidia-docker.list

sudo apt update && sudo apt install -y nvidia-container-toolkit
sudo systemctl restart docker

Add to docker-compose.yml:

services:
  bitbonsai-backend:
    deploy:
      resources:
        reservations:
          devices:
            - driver: nvidia
              count: 1
              capabilities: [gpu]

Network Requirements

Single Node

Port	Service	Required
4210	Frontend UI	Yes
3100	Backend API	Yes (internal)
5432	PostgreSQL	Yes (internal)

Only port 4210 needs to be accessible from your browser. Ports 3100 and 5432 are internal to Docker.

Multi-Node Setup

Port	Service	Required
3100	Main node API	Yes (for child nodes)
2049	NFS Server	Yes (if using NFS)
111	NFS RPC	Yes (if using NFS)

Bandwidth recommendation: 1 Gbps+ between nodes for NFS shared storage.

Storage Considerations

Disk Space

System Space (20 GB minimum)

Docker images: ~5 GB
Database: 100 MB - 1 GB (scales with library size)
Temp files: 2-5 GB per active job
Logs: 1-2 GB (rotated automatically)

Video Library Space

BitBonsai replaces original files after successful encoding.During encoding:

Original file: 100 MB (example)
Temp encoded file: 40 MB (60% savings)
Total: 140 MB (peak usage)

After encoding:

New encoded file: 40 MB
Savings: 60 MB (original deleted)

Storage Performance

Storage Type	Use Case	Notes
HDD	Video library	Acceptable (sequential reads)
SSD	Temp directory	Recommended for faster I/O
NFS	Multi-node shared storage	1 Gbps+ network required

Supported Operating Systems

Linux (Recommended)
Windows (WSL2)
macOS

Tested distributions:

Ubuntu 20.04+ / Debian 11+
Fedora 36+
Arch Linux
Unraid 6.10+ (via Community Apps)

Why Linux?

Best Docker performance
Native hardware transcoding support
Lowest resource overhead

Next Steps

Install with Docker

Deploy BitBonsai using Docker Compose

Install on Unraid

Use Unraid Community Applications

Getting Started

Installation

User Guide

Advanced

Support

System Requirements

Minimum Requirements

Basic Setup

Recommended Specifications

Medium Library

Large Library

Performance Factors

Software Requirements

Docker & Docker Compose

Hardware Transcoding (Optional)

Supported GPUs

NVIDIA

Intel

AMD

Docker GPU Passthrough

Network Requirements

Single Node

Multi-Node Setup

Storage Considerations

Disk Space

Storage Performance

Supported Operating Systems

Next Steps

Install with Docker

Install on Unraid

​Minimum Requirements

Basic Setup

​Recommended Specifications

Medium Library

Large Library

​Performance Factors

​Software Requirements

​Docker & Docker Compose

​Hardware Transcoding (Optional)

​Supported GPUs

NVIDIA

Intel

AMD

​Docker GPU Passthrough

​Network Requirements

​Single Node

​Multi-Node Setup

​Storage Considerations

​Disk Space

​Storage Performance

​Supported Operating Systems

​Next Steps

Install with Docker

Install on Unraid

Minimum Requirements

Recommended Specifications

Performance Factors

Software Requirements

Docker & Docker Compose

Hardware Transcoding (Optional)

Supported GPUs

Docker GPU Passthrough

Network Requirements

Single Node

Multi-Node Setup

Storage Considerations

Disk Space

Storage Performance

Supported Operating Systems

Next Steps