Docker Installation

Deploy BitBonsai using Docker containers for simplified installation and updates.

Prerequisites

Before installing, ensure you have:

Requirement	Minimum Version	Check Command
Docker	20.10+	`docker --version`
Docker Compose	2.0+	`docker compose version`
Disk Space	100GB+	For temporary encoding files
RAM	8GB+	For parallel encoding jobs

BitBonsai requires access to your video library via volume mounts. Plan your directory structure before installation.

Quick Start

Create Configuration Directory

mkdir -p ~/bitbonsai
cd ~/bitbonsai

Create docker-compose.yml

Create a docker-compose.yml file with the following configuration:

docker-compose.yml

version: '3.8'

services:
  postgres:
    image: postgres:15
    container_name: bitbonsai-postgres
    restart: unless-stopped
    environment:
      POSTGRES_DB: bitbonsai
      POSTGRES_USER: bitbonsai
      POSTGRES_PASSWORD: changeme
    volumes:
      - postgres-data:/var/lib/postgresql/data
    ports:
      - "5432:5432"
    healthcheck:
      test: ["CMD-SHELL", "pg_isready -U bitbonsai"]
      interval: 10s
      timeout: 5s
      retries: 5

  bitbonsai-backend:
    image: ghcr.io/bitbonsai/backend:latest
    container_name: bitbonsai-backend
    restart: unless-stopped
    depends_on:
      postgres:
        condition: service_healthy
    environment:
      DATABASE_URL: postgresql://bitbonsai:changeme@postgres:5432/bitbonsai
      PORT: 3100
      NODE_ENV: production
    volumes:
      - /path/to/your/videos:/videos
      - /path/to/temp:/tmp/bitbonsai
    ports:
      - "3100:3100"

  bitbonsai-frontend:
    image: ghcr.io/bitbonsai/frontend:latest
    container_name: bitbonsai-frontend
    restart: unless-stopped
    depends_on:
      - bitbonsai-backend
    environment:
      API_URL: http://bitbonsai-backend:3100
    ports:
      - "4210:4210"

volumes:
  postgres-data:

Replace /path/to/your/videos and /path/to/temp with actual paths on your host system.

Configure Environment

Edit the docker-compose.yml file to set:

POSTGRES_PASSWORD: Change changeme to a secure password
DATABASE_URL: Update password in connection string to match
Volume paths: Point to your actual video library and temp directory

Start Services

docker compose up -d

This will:

Pull Docker images from GitHub Container Registry
Create PostgreSQL database
Start backend API and frontend UI
Apply database migrations automatically

Verify Installation

Check service health:

docker compose ps

All services should show Up (healthy) or Up status.

Access the UI

Open your browser to:

BitBonsai Web Interface

http://localhost:4210

Default setup includes:

Frontend: http://localhost:4210
Backend API: http://localhost:3100
PostgreSQL: localhost:5432

Environment Variables

Backend Configuration

Variable	Description	Default	Required
`DATABASE_URL`	PostgreSQL connection string	-	Yes
`PORT`	API server port	3100	No
`NODE_ENV`	Environment mode	production	No
`LOG_LEVEL`	Logging verbosity (error, warn, info, debug)	info	No

Frontend Configuration

Variable	Description	Default	Required
`API_URL`	Backend API URL (internal Docker network)	-	Yes

Database Configuration

Variable	Description	Default	Required
`POSTGRES_DB`	Database name	bitbonsai	Yes
`POSTGRES_USER`	Database user	bitbonsai	Yes
`POSTGRES_PASSWORD`	Database password	-	Yes

For production deployments, use Docker secrets or environment files instead of hardcoding credentials.

Volume Mounts

Video Library Mount

volumes:
  - /path/to/your/videos:/videos

Purpose: Provides read/write access to your video files for scanning and encoding. Requirements:

Must be an absolute path on the host system
User inside container must have read/write permissions
Sufficient free space for encoded outputs (typically 50-70% of original size)

Examples:

# Single library
- /mnt/media/movies:/videos

# Multiple libraries (mount parent directory)
- /mnt/media:/videos
  # BitBonsai will scan subdirectories: /videos/movies, /videos/tv, etc.

Temporary Files Mount

volumes:
  - /path/to/temp:/tmp/bitbonsai

Purpose: Stores temporary encoding files during transcoding operations. Requirements:

Fast storage recommended (SSD/NVMe preferred)
Minimum free space: 2× largest video file size
Cleared automatically after successful encoding

Do not use /tmp on the host if it’s a tmpfs (RAM disk). Encoding generates large temporary files.

PostgreSQL Data

volumes:
  - postgres-data:/var/lib/postgresql/data

Purpose: Persistent storage for database files. Backup: Use docker compose exec postgres pg_dump for database backups.

Advanced Configuration

Custom Ports
Hardware Acceleration
Resource Limits
Logging

Change external ports without modifying container ports:

services:
  bitbonsai-frontend:
    ports:
      - "8080:4210"  # Access on host port 8080

  bitbonsai-backend:
    ports:
      - "8081:3100"  # API on host port 8081

Enable GPU acceleration for faster encoding:

services:
  bitbonsai-backend:
    devices:
      - /dev/dri:/dev/dri  # Intel/AMD GPU
    # OR for NVIDIA:
    # runtime: nvidia
    # environment:
    #   NVIDIA_VISIBLE_DEVICES: all

Requires NVIDIA Container Toolkit for NVIDIA GPUs.

Limit CPU and memory usage:

services:
  bitbonsai-backend:
    deploy:
      resources:
        limits:
          cpus: '8.0'
          memory: 16G
        reservations:
          cpus: '4.0'
          memory: 8G

Configure log retention and rotation:

services:
  bitbonsai-backend:
    logging:
      driver: "json-file"
      options:
        max-size: "10m"
        max-file: "3"

First Startup

After starting BitBonsai for the first time:

Database Migrations

Backend automatically applies database migrations on startup. Check logs:

docker compose logs bitbonsai-backend

Look for:

[Nest] INFO [Database] Migrations applied successfully
[Nest] INFO [Bootstrap] Application listening on port 3100

Add Video Library

Navigate to Settings → Libraries in the UI and add your first library:

Name: Movies
Path: /videos/movies (relative to container mount)
Type: Movies or TV Shows

Use the /videos prefix since that’s the container mount point, not your host path.

Run Initial Scan

Click Scan Library to index your video files. Monitor progress in the Jobs tab.

Updating BitBonsai

Pull latest images and restart containers:

docker compose pull
docker compose up -d

Database migrations apply automatically on startup.

Always backup your database before updating:

docker compose exec postgres pg_dump -U bitbonsai bitbonsai > backup.sql

Troubleshooting

Container Won’t Start

Check logs for errors:

docker compose logs bitbonsai-backend
docker compose logs bitbonsai-frontend

Cannot Access UI

Verify container is running and port mapping:

docker compose ps
curl http://localhost:4210

Database Connection Errors

Ensure PostgreSQL is healthy:

docker compose exec postgres pg_isready -U bitbonsai

If connection fails, check DATABASE_URL matches PostgreSQL credentials.

Permission Errors

Fix volume mount permissions:

# Find container user ID
docker compose exec bitbonsai-backend id

# Adjust host directory ownership
sudo chown -R 1000:1000 /path/to/your/videos

Out of Disk Space

Check temporary directory usage:

du -sh /path/to/temp

Clear old temporary files:

docker compose exec bitbonsai-backend rm -rf /tmp/bitbonsai/*

Next Steps

First Library Scan

Add your video library and run your first scan

Encoding Configuration

Configure HEVC/AV1 encoding presets

Multi-Node Setup

Scale encoding with worker nodes

Backup & Recovery

Backup strategies for database and configuration

Getting Started

Installation

User Guide

Advanced

Support

Docker Installation

Prerequisites

Quick Start

Access the UI

BitBonsai Web Interface

Environment Variables

Backend Configuration

Frontend Configuration

Database Configuration

Volume Mounts

Video Library Mount

Temporary Files Mount

PostgreSQL Data

Advanced Configuration

First Startup

Updating BitBonsai

Troubleshooting

Container Won’t Start

Cannot Access UI

Database Connection Errors

Permission Errors

Out of Disk Space

Next Steps

First Library Scan

Encoding Configuration

Multi-Node Setup

Backup & Recovery

​Prerequisites

​Quick Start

​Access the UI

BitBonsai Web Interface

​Environment Variables

​Backend Configuration

​Frontend Configuration

​Database Configuration

​Volume Mounts

​Video Library Mount

​Temporary Files Mount

​PostgreSQL Data

​Advanced Configuration

​First Startup

​Updating BitBonsai

​Troubleshooting

​Container Won’t Start

​Cannot Access UI

​Database Connection Errors

​Permission Errors

​Out of Disk Space

​Next Steps

First Library Scan

Encoding Configuration

Multi-Node Setup

Backup & Recovery

Prerequisites

Quick Start

Access the UI

Environment Variables

Backend Configuration

Frontend Configuration

Database Configuration

Volume Mounts

Video Library Mount

Temporary Files Mount

PostgreSQL Data

Advanced Configuration

First Startup

Updating BitBonsai

Troubleshooting

Container Won’t Start

Cannot Access UI

Database Connection Errors

Permission Errors

Out of Disk Space

Next Steps