ViTransfer Documentation

Overview

ViTransfer is a self-hosted, open-source video review and approval platform designed for video professionals. It enables secure video sharing, timestamped feedback, and streamlined approval workflows without relying on third-party services.

Key Features

System Requirements

Minimum Requirements

Software Dependencies

• Docker: Version 20.10 or higher
• Docker Compose: Version 2.0 or higher
• FFmpeg: Included in Docker image (no manual installation needed)

Installation

Quick Start with Docker Hub

The fastest way to get ViTransfer running is using the pre-built Docker image from Docker Hub.

Step 1: Create Project Directory

Step 2: Download Configuration Files

Step 3: Generate Required Secrets

Use hex for database/Redis (URL-safe), base64 for encryption/JWT/share secrets.

Step 4: Configure Environment Variables

Edit the .env file and set at minimum:

Step 5: Start ViTransfer

Step 6: Access the Application

Open your browser and navigate to:

Building from Source

If you want to build from source instead of using the Docker Hub image:

Configuration

Environment Variables

ViTransfer reads configuration from the .env file (see .env.example for defaults). Key settings:

Core Settings

Database & Redis

Security Keys

Admin Account

Optional

Features Guide

Project Management

Creating a Project

1. Log in as an admin and click "New Project" from the dashboard.
2. Enter the project title, optional description, and company/client name.
3. Add an optional primary recipient (name/email) for notifications.
4. Select authentication mode: Password, Email OTP, Both, or None.
5. Set a share password if using password-based modes (auto-generated by default).
6. Toggle guest mode if you want view-only access; guests see the latest version by default.
7. Create the project, then adjust watermark, download, and notification settings in Project Settings.

Watermarking

ViTransfer supports project-level watermarking to protect preview renders:

• Enable/Disable: Control watermarks globally and per project.
• Custom Text: Override the default watermark text (up to 100 characters).

Video Upload & Processing

Uploading Videos

ViTransfer uses the TUS protocol for resumable uploads and validates MP4/MOV headers before starting:

1. Open the project and click "Upload Video".
2. Enter a video name and optional version label.
3. Select your MP4/MOV file.
4. Start the upload; it will resume automatically after interruptions.

Automatic Transcoding

Videos are automatically transcoded to watermarked previews (720p/1080p based on project/global settings). Original files are preserved for download once approved.

Review & Collaboration

Timestamped Comments

Add timestamped feedback tied to the playback position and keep discussions organized with threaded replies. Email notifications are sent when SMTP is configured.

Guest Mode

Share links support Password, Email OTP, Both, or guest access (when enabled). Guest mode is view-only and, by default, shows the latest version only. Downloads and assets remain blocked until videos are approved.

Approval Workflow

Clients on the project share page can approve when allowed. Admins can approve or unapprove individual video versions; projects move between IN REVIEW and APPROVED, and you can create dedicated SHARE ONLY projects for delivery-only access. Auto-approval can mark the project approved when every video has an approved version. After approval, clients can download original-quality video files and, if enabled, any attached assets (single files or ZIP bundles).

Asset Management

Attaching Supporting Files

Attach related assets to keep everything organized:

• Images/Thumbnails: JPG, PNG, GIF, WEBP, BMP, TIFF, SVG
• Audio: MP3, WAV, AAC, FLAC, OGG, M4A, WMA
• Documents: PDF, DOC/DOCX, TXT, RTF
• Project Files & Archives: PRPROJ, AEP, FCP, DaVinci, ZIP/RAR/7Z
• Supporting Videos: MP4, MOV, AVI, MKV, MXF
• Captions/Subtitles: SRT, VTT, ASS/SSA, SUB

Assets are extension-checked at upload, validated by magic bytes in the worker, and categorized (image/thumbnail, audio, video, subtitle, project, document, other). Admins can always download; clients/guests can download single assets or ZIP bundles only when the video is approved and the project’s “Allow asset download” setting is enabled.

You can set a custom thumbnail per video version using an uploaded image asset; if removed, the system falls back to the generated thumbnail.

Analytics & Insights

Activity Tracking

Monitor project engagement with built-in analytics (when enabled in Security Settings):

• Page visits per video/project
• Download events

Security events (rate limits, access violations) and advanced security settings (rate limits, token TTLs, hotlink protection) are available in the Security dashboard when enabled.

API Reference

ViTransfer provides authenticated JSON endpoints for the admin dashboard and share links. All requests use bearer tokens in the Authorization header.

Authentication

Admin login returns access and refresh tokens:

Refresh tokens with POST /api/auth/refresh. Passkey enrollment and authentication live under /api/auth/passkey/* (optional).

Share Link Authentication

• POST /api/share/[token]/verify – verify a project password.
• POST /api/share/[token]/send-otp – send an email OTP to a configured recipient.
• POST /api/share/[token]/verify-otp – verify OTP and issue a share token.
• POST /api/share/[token]/guest – guest access when enabled.

Projects API

• GET /api/projects – list projects (admin).
• POST /api/projects – create a project (title, description, authMode, sharePassword, recipient info).
• GET /api/projects/:id – retrieve project details with videos, comments, and recipients.
• PATCH /api/projects/:id – update status, authentication mode, watermark/download settings, notifications, and guest options.
• DELETE /api/projects/:id – delete a project and its files.

Videos API

• POST /api/videos – create a video record before upload (projectId, name, versionLabel, originalFileName, originalFileSize).
• TUS /api/uploads (pages API) – resumable uploads for videos and assets.
• PATCH /api/videos/:id – update name, version label, or approval state.
• DELETE /api/videos/:id – remove a video and associated files.
• /api/videos/:id/assets and related routes – create/list/delete assets, set thumbnails, generate download/zip tokens, or copy assets between versions.

Comments API

• GET /api/comments?projectId=... – list comments for a project.
• POST /api/comments – create a comment or reply (projectId, videoId, content, timestamp, optional parentId).
• DELETE /api/comments/:id – delete a comment.

Analytics API

• POST /api/analytics/visit – record a page visit (used by share pages).
• GET /api/analytics – aggregated analytics for all projects (admin).
• GET /api/analytics/:id – analytics for a single project (admin).

Deployment Options

Standard Docker

The recommended deployment method using Docker Compose:

Unraid

Use the Docker Compose Manager plugin on Unraid (recommended flow in README):

1. Install "Docker Compose Manager" via the Unraid Apps tab.
2. Download docker-compose.unraid.yml and .env.example from the repo.
3. Generate secrets, copy .env.example to .env, and fill required values.
4. Check and adjust volume paths in docker-compose.unraid.yml for your Unraid storage.
5. Create a new stack in Compose Manager, paste the compose file, and add your .env contents.
6. Compose Up, wait for initialization, then access http://UNRAID-IP:4321.

TrueNAS Scale

1. Navigate to "Apps" in TrueNAS web interface
2. Click "Discover Apps"
3. Search for "ViTransfer" or use custom app
4. Configure application settings:
   • Set container image: crypt010/vitransfer:latest
   • Configure storage (recommend separate dataset)
   • Set environment variables
5. Deploy application

Podman with Quadlet

Use the Quadlet templates in the quadlet/ directory for systemd-managed Podman deployments.

Create Quadlet File

Create ~/.config/containers/systemd/vitransfer.container (or copy quadlet/vitransfer-app.container) and set the required secrets:

Run the accompanying Postgres and Redis Quadlet units from quadlet/ or point the app container to existing services.

Enable and Start

Reverse Proxy Setup

Troubleshooting

Quick Checks

• Review logs: docker-compose logs (add app or worker for specific services).
• Verify .env is complete and matches your compose file.
• Ensure disk space is available: df -h.
• If uploads fail, confirm proxy/body size limits and retry with a small file.

Security Best Practices

Secret Management

• Generate Strong Secrets: Use openssl rand -hex 32 for DB/Redis (URL-safe) and openssl rand -base64 32/64 for encryption/JWT/share secrets
• Rotate Regularly: Change secrets periodically, especially after team member changes

Access Control

• Strong Admin Password: Use minimum 16 characters with mixed case, numbers, symbols
• Limit Admin Accounts: Create admin accounts only when necessary
• Guest Mode Security: Use only for non-sensitive content
• Authentication Protection: Enable project passwords and/or OTP for sensitive content
• Passkeys: Enable passkey (WebAuthn) login for admins for phishing-resistant auth

Network Security

• Use HTTPS: Always deploy with SSL/TLS in production
• Firewall Rules: Restrict access to database and internal services
• Reverse Proxy: Use a hardened tunnel/proxy (tested with Cloudflare Tunnels)
• Rate Limiting: Built-in rate limits for auth, share, and uploads; tune in Security Settings

File Security

• Upload Validation: Server-side extension and magic-byte checks for videos and assets
• Storage Permissions: Ensure proper file system permissions on data volumes

Database Security

• Strong DB Password: Use complex database password (see secret management)
• Network Isolation: Keep database on private Docker network

Monitoring & Logging

• Security Events: Track rate-limit hits, OTP attempts, and access violations (toggle in Security Settings)
• Monitor Failed Logins: Review security events for suspicious authentication attempts
• Regular Reviews: Periodically review access and download activity (Analytics and Security pages)

Update Management

• Stay Updated: Regularly update to latest ViTransfer version
• Security Patches: Apply security updates promptly
• Dependency Updates: Keep Docker and system dependencies current
• Changelog Review: Read release notes for security advisories

Incident Response

If you suspect a security breach:

1. Isolate: Immediately disconnect affected systems from network
2. Assess: Review logs to determine scope of breach
3. Contain: Change all passwords and secrets
4. Notify: Inform affected users and stakeholders
5. Report: If vulnerability in ViTransfer, report to maintainers
6. Recover: Restore from clean backups if necessary
7. Review: Analyze incident and improve security measures