Migrating from PeerTube to Vidra
Vidra is fully compatible with PeerTube's REST API (v8.1.0), which means your existing PeerTube clients, embeds, and federation peers continue to work after migration. This guide walks you through the complete process of importing your PeerTube instance into Vidra.
Migration Paths
Vidra supports two migration approaches depending on your comfort level and requirements:
| Approach | Best For | Downtime | Complexity |
|---|---|---|---|
| API-Driven Migration | Operators who want a managed, auditable process with dry-run support | Minutes (final cutover only) | Low |
| Manual Migration | Operators who need full control over every step, or have heavily customized PeerTube instances | Varies | Medium-High |
Both approaches follow the same general workflow:
What Gets Migrated
| Data | Supported | Notes |
|---|---|---|
| Users & Accounts | Yes | Usernames, emails, roles, avatars. Passwords require users to reset (bcrypt hashes are not portable between implementations). |
| Channels | Yes | Names, descriptions, avatars, banners, all metadata |
| Videos | Yes | Metadata, privacy settings, tags, categories, languages, licences |
| Video Files | Yes | Web video files, HLS segments, thumbnails, previews |
| Comments | Yes | Full thread trees with parent-child relationships preserved |
| Playlists | Yes | Playlist metadata and ordered item lists |
| Captions/Subtitles | Yes | VTT and SRT files with language metadata |
| Subscriptions | Yes | Channel follow relationships |
| Abuse Reports | Yes | Report content and status |
| Blocklists | Yes | Account and server-level blocks |
| Instance Config | Partial | Name, description, and contact info migrate; server-level settings require manual configuration |
| Federation Peers | Manual | ActivityPub followers/following need re-federation after cutover |
| OAuth Clients | Manual | Third-party OAuth apps must be re-registered |
| Plugins | No | PeerTube plugins are not compatible with Vidra's plugin system |
Prerequisites
Before starting a migration, ensure you have:
- A running Vidra instance (Getting Started guide)
- Vidra database migrations applied (
make migrate-up) - Admin account created on the Vidra instance
- Network access from Vidra to your PeerTube PostgreSQL database (for API-driven migration)
- Access to PeerTube's media storage directory or S3 bucket
- A maintenance window scheduled (for final cutover)
- PeerTube database backup taken (
pg_dump)
PeerTube-to-Vidra Data Mapping
Understanding how PeerTube concepts map to Vidra helps troubleshoot any migration issues:
| PeerTube Concept | Vidra Equivalent | Key Differences |
|---|---|---|
| Account + User | User | Vidra merges these into a single users table |
| Video Channel | Channel | name → handle, accountId → account_id (via username match) |
| Video | Video | Same fields; Vidra adds IPFS CID and IOTA payment fields |
| Video File | Video File | Web-video and HLS files stored at same relative paths |
| Video Comment | Comment | parent_id preserves threading; Vidra adds approval workflow |
| Video Playlist | Playlist | Direct mapping including privacy levels |
| Playlist Element | Playlist Item | Position/ordering preserved |
| Video Caption | Caption | Language, format (VTT/SRT), and file reference |
| User Subscription | Subscription | Channel follow relationship |
| Abuse | Abuse Report | Report content, status, and admin messages |
| Server Blocklist | Server Block | Instance-level federation blocks |
| Account Blocklist | Account Block | User-level blocks |
Estimated Migration Times
These estimates assume a standard PeerTube instance. Large or heavily customized instances may take longer.
| Instance Size | Users | Videos | Database Import | Media Copy | Total |
|---|---|---|---|---|---|
| Small | < 100 | < 500 | ~2 min | ~10 min | ~15 min |
| Medium | 100-1,000 | 500-5,000 | ~10 min | ~1 hour | ~1.5 hours |
| Large | 1,000+ | 5,000+ | ~30 min | Hours (depends on storage) | Hours |
Media copy time depends heavily on storage size and transfer speed between your PeerTube storage and Vidra storage backend.
Next Steps
- Plan your migration — Inventory your PeerTube data and choose a migration path
- API-driven migration — Use Vidra's Migration ETL API for a managed import
- Manual migration — Step-by-step guide for manual database and media migration
- Storage migration — Move video files, thumbnails, and streaming playlists
- Cutover and validation — DNS switch, post-migration checks, and rollback plan
- Troubleshooting — Common issues and solutions