Introduction to Shoebox

Shoebox is a digital solution for organizing and preserving your videos over a lifetime.

The Digital Shoebox Concept

Remember how previous generations kept their memories in physical shoeboxes at their parents' homes? Those boxes filled with photographs, negatives, and mementos that captured life's precious moments.

Shoebox aims to recreate that experience for the digital age. Instead of photos getting lost in the endless stream of cloud services or social media platforms, Shoebox provides a dedicated space for your videos - a digital equivalent of that cherished box in your closet.

What Makes Shoebox Different

Shoebox is not trying to compete with immich, Google Photos, or other photo management services.

The main purpose of Shoebox is to help you:

• Find original videos export(copy) to a defined location, allowing you to easily import into a video editor of choice. Create highlights, collages, etc.
• Organize your videos over a lifetime for easy recall and future use. Have a coffee, review new videos cataloguing your memories as your kids grow.
• Preserve video memories in a way that makes them accessible and workable

While other services focus on viewing and sharing, Shoebox focuses on organization and preservation with the specific goal of making your video content useful for future creative projects.

Tech Stack

• Backend: Rust with Axum web framework
• Frontend: React with TypeScript
• Database: SQLite/PostgreSQL via SQLx
• Media Processing: FFmpeg
• Deployment: Docker/Kubernetes support

Installation

Shoebox can be installed in several ways, depending on your environment and preferences.

Prerequisites

Before installing Shoebox, ensure you have the following prerequisites:

• FFmpeg (for video processing)
• Access to storage for your videos, thumbnails, and exports

Installation Methods

Docker

The simplest way to run Shoebox is using Docker:

# Pull the latest image
docker pull ghcr.io/slackspace-io/shoebox:latest

# Run the container
docker run -d \
  -p 3000:3000 \
  -v /path/to/your/videos:/mnt/videos:ro \
  -v /path/to/your/exports:/app/exports \
  -v /path/to/thumbnails:/app/thumbnails \
  -v /path/to/data:/app/data \
  --name shoebox \
  ghcr.io/slackspace-io/shoebox:latest

Docker Compose

For a more complete setup, you can use Docker Compose:

# Clone the repository
git clone https://github.com/slackspace-io/shoebox.git
cd shoebox

# Edit the docker-compose.yml file to configure your media source paths
# Start the application
docker-compose up -d

Kubernetes with Helm

For Kubernetes deployments, Shoebox provides a Helm chart. See the Helm Chart page for detailed instructions.

Development Setup

If you want to run Shoebox for development:

# Clone the repository
git clone https://github.com/slackspace-io/shoebox.git
cd shoebox

# Run the backend
cargo run

# In a separate terminal, run the frontend
cd frontend
yarn install
yarn dev

The frontend development server will be available at http://localhost:5173, and the backend server will be available at http://localhost:3000.

Helm Chart Installation

This page provides detailed instructions for deploying Shoebox on Kubernetes using the Helm chart.

Prerequisites

• Kubernetes 1.19+
• Helm 3.2.0+
• PV provisioner support in the underlying infrastructure (if persistence is enabled)

Getting Started

Adding the Helm Repository

# Add the Shoebox Helm repository
helm repo add shoebox https://slackspace-io.github.io/shoebox
helm repo update

Installing the Chart

To install the chart with the release name shoebox:

helm install shoebox shoebox/shoebox

Using a Specific Image Version

By default, the chart uses the preview tag for the Shoebox image. For production environments, it's recommended to use a specific version:

helm install shoebox shoebox/shoebox --set image.tag=v1.0.0

Using a Private Registry

If you're using a private registry for the Shoebox image, you'll need to create a secret with your registry credentials:

kubectl create secret docker-registry regcred \
  --docker-server=ghcr.io \
  --docker-username=<your-username> \
  --docker-password=<your-token> \
  --docker-email=<your-email>

Then, specify the secret in your Helm install command:

helm install shoebox shoebox/shoebox --set imagePullSecrets[0].name=regcred

Configuration

The Shoebox Helm chart offers extensive configuration options through its values.yaml file. You can override these values using the --set flag or by providing your own values file.

Media Source Paths Configuration

One of the key features of Shoebox is the ability to specify the original location of videos. This is configured through the config.mediaSourcePaths parameter.

The mediaSourcePaths parameter accepts a comma-separated list of paths. Each path can be configured in two formats:

Named Section Format (Recommended)

name:/path/to/videos;/original/path;original_extension

Where:

• name is a descriptive name for the media source (e.g., "bmpcc", "gopro", etc.)
• /path/to/videos is the path where the videos are mounted in the container (required)
• /original/path (optional) is the original location of the videos on the source system
• original_extension (optional) is the original file extension of the videos. If not provided but original_path is, it will use the same extension as the scan path.

For example:

config:
  mediaSourcePaths: "bmpcc:/mnt/videos;/home/user/videos;mp4,gopro:/mnt/other-videos;/media/external/videos"

For better readability, you can also use YAML's multi-line string syntax:

config:
  mediaSourcePaths: >-
    bmpcc:/mnt/videos;/home/user/videos;mp4,
    gopro:/mnt/other-videos;/media/external/videos

Both configurations specify two named media source paths:

1. bmpcc with scan path /mnt/videos, original path /home/user/videos, and original extension mp4
2. gopro with scan path /mnt/other-videos, original path /media/external/videos, and using the same extension as the scan path

Legacy Format (Backward Compatible)

The older format without named sections is still supported:

/path/to/videos;/original/path;original_extension

For example:

config:
  mediaSourcePaths: "/mnt/videos;/home/user/videos;mp4,/mnt/other-videos;/media/external/videos"

You can set this configuration when installing the chart:

helm install shoebox shoebox/shoebox \
  --set config.mediaSourcePaths="/mnt/videos;/home/user/videos;mp4,/mnt/other-videos;/media/external/videos"

Other Configuration Parameters

Image Configuration

Application Configuration

Persistence Configuration

PostgreSQL Configuration

Examples

Using SQLite with Persistence

helm install shoebox shoebox/shoebox \
  --set persistence.data.enabled=true \
  --set persistence.thumbnails.enabled=true \
  --set persistence.exports.enabled=true \
  --set persistence.media.existingClaim=media-pvc

Using PostgreSQL

helm install shoebox shoebox/shoebox \
  --set postgresql.enabled=true \
  --set postgresql.postgresqlPassword=mypassword \
  --set persistence.thumbnails.enabled=true \
  --set persistence.exports.enabled=true \
  --set persistence.media.existingClaim=media-pvc

Configuring Multiple Media Source Paths with Original Locations

# Using a single line
helm install shoebox shoebox/shoebox \
  --set config.mediaSourcePaths="bmpcc:/mnt/videos;/home/user/videos;mp4,gopro:/mnt/other-videos;/media/external/videos" \
  --set persistence.thumbnails.enabled=true \
  --set persistence.exports.enabled=true \
  --set persistence.media.existingClaim=media-pvc

# Or using a values file with the multi-line syntax for better readability
cat > values-custom.yaml << EOF
config:
  mediaSourcePaths: >-
    bmpcc:/mnt/videos;/home/user/videos;mp4,
    gopro:/mnt/other-videos;/media/external/videos
persistence:
  thumbnails:
    enabled: true
  exports:
    enabled: true
  media:
    existingClaim: media-pvc
EOF

helm install shoebox shoebox/shoebox -f values-custom.yaml

Disabling Persistence (for testing)

helm install shoebox shoebox/shoebox \
  --set persistence.data.enabled=false \
  --set persistence.thumbnails.enabled=false \
  --set persistence.exports.enabled=false \
  --set persistence.media.enabled=false

Upgrading

To 1.0.0

This is the first stable release of the Shoebox chart.

Configuration

Shoebox offers various configuration options to customize its behavior according to your needs.

Environment Variables

Shoebox can be configured using environment variables. Here are the main configuration options:

Server Configuration

Database Configuration

Media Configuration

Media Source Paths Configuration

The MEDIA_SOURCE_PATHS environment variable is particularly important as it defines where Shoebox looks for videos. This variable accepts a comma-separated list of paths.

Basic Usage

For basic usage, you can specify one or more paths:

MEDIA_SOURCE_PATHS=/path/to/videos,/path/to/more/videos

Advanced Configuration with Original Locations

A recent enhancement allows you to specify the original location of videos, which is useful when the path in your container or server differs from the original path where the videos were created or stored.

Each path can include additional configuration options using the following format:

/path/to/videos;/original/path;original_extension

Where:

• /path/to/videos is the path where the videos are mounted in the container or server
• /original/path (optional) is the original location of the videos on the source system
• original_extension (optional) is the original file extension of the videos

For example:

MEDIA_SOURCE_PATHS=/mnt/videos;/home/user/videos;mp4,/mnt/other-videos;/media/external/videos

This configuration specifies two media source paths:

1. /mnt/videos with original path /home/user/videos and original extension mp4
2. /mnt/other-videos with original path /media/external/videos and no specific extension

Why Specify Original Locations?

Specifying the original location of videos is useful for several reasons:

1. Preserving metadata: When exporting videos, Shoebox can include information about their original location, which helps with organization and traceability.
2. Compatibility with external tools: Some video editing tools may use absolute paths in project files. By knowing the original path, Shoebox can help maintain compatibility.
3. Migration between systems: If you move your videos from one system to another, specifying the original location helps maintain consistency in your workflow.

Configuration Files

Currently, Shoebox does not support configuration files directly. All configuration is done through environment variables or command-line arguments.

For Kubernetes deployments using the Helm chart, configuration is done through the values.yaml file or by setting values with the --set flag. See the Helm Chart page for more details.

Using Shoebox

This guide covers the basic usage of Shoebox for organizing and preserving your videos.

Accessing the Web Interface

After installing Shoebox, you can access the web interface by navigating to:

http://<your-server-address>:3000

If you're running Shoebox locally, this would be:

http://localhost:3000

Organizing Videos

Shoebox helps you organize your videos by providing a structured way to catalog and tag them.

Reviewing New Videos

When you first start Shoebox, it will scan your configured media source paths for videos. New videos will appear in the "Unreviewed" section.

1. Navigate to the "Unreviewed" page
2. For each video:
   • Watch the preview
   • Add tags and descriptions
   • Mark as reviewed

Tagging Videos

Tags help you categorize your videos for easier searching and filtering:

1. Select a video
2. Add relevant tags (e.g., "birthday", "vacation", "family")
3. Save your changes

Searching and Filtering

You can search for videos based on various criteria:

1. Use the search bar to find videos by name, tag, or description
2. Use filters to narrow down results by date, duration, or other metadata
3. Save your favorite searches for quick access

Exporting Videos

One of the key features of Shoebox is the ability to export videos for use in external editing tools.

Basic Export

To export a video:

1. Select the video you want to export
2. Click the "Export" button
3. Choose the export location
4. Wait for the export to complete

The exported video will be copied to the specified location, preserving its original quality.

Export with Original Path Information

If you've configured Shoebox with original path information (see Configuration), the export will include metadata about the video's original location. This is particularly useful when:

1. You're exporting videos for use in a video editing project
2. You need to maintain references to the original file locations
3. You're migrating videos between systems

System Information and Management

Shoebox provides system information and management tools to help you maintain your video collection.

Viewing System Information

To view system information:

1. Navigate to the "System" page
2. Here you can see:
   • Storage usage
   • Number of videos
   • Database status
   • Application version

Managing Storage

To manage storage:

1. Regularly check the storage usage on the System page
2. Consider archiving older videos if storage is running low
3. Ensure your export and thumbnail directories have sufficient space

Best Practices

Here are some best practices for using Shoebox effectively:

1. Regular Reviews: Set aside time to review new videos regularly
2. Consistent Tagging: Develop a consistent tagging system
3. Backup: Regularly backup your Shoebox database and configuration
4. Storage Planning: Plan your storage needs based on your video collection size
5. Original Paths: When possible, configure Shoebox with information about the original location of your videos