Skip to main content

Planning Your Migration

A successful PeerTube-to-Vidra migration starts with careful planning. This page helps you inventory your existing data, choose a migration strategy, and prepare both environments.

Step 1: Inventory Your PeerTube Instance​

Connect to your PeerTube PostgreSQL database and run these queries to understand the scope of your migration:

-- Users and accounts
SELECT COUNT(*) AS users FROM "user";
SELECT COUNT(*) AS accounts FROM account;

-- Channels
SELECT COUNT(*) AS channels FROM "videoChannel";

-- Videos by state
SELECT state, COUNT(*) FROM video GROUP BY state;

-- Total video storage
SELECT
  pg_size_pretty(SUM(size)) AS total_size,
  COUNT(*) AS file_count
FROM "videoFile";

-- HLS streaming playlists
SELECT COUNT(*) AS hls_playlists FROM "videoStreamingPlaylist";

-- Comments
SELECT COUNT(*) AS comments FROM "videoComment";

-- Playlists
SELECT COUNT(*) AS playlists FROM "videoPlaylist";
SELECT COUNT(*) AS playlist_items FROM "videoPlaylistElement";

-- Captions
SELECT COUNT(*) AS captions FROM "videoCaption";

-- Subscriptions (channel follows)
SELECT COUNT(*) AS subscriptions FROM "actorFollow"
  WHERE "actorFollow"."targetActorId" IN (
    SELECT a.id FROM actor a WHERE a."videoChannelId" IS NOT NULL
  );

-- Abuse reports
SELECT COUNT(*) AS abuse_reports FROM abuse;

Record these numbers — you'll use them to verify the migration was complete.

Step 2: Assess Storage​

Identify where PeerTube stores media files:

# Default PeerTube storage paths
du -sh /var/www/peertube/storage/videos/          # Web video files
du -sh /var/www/peertube/storage/streaming-playlists/  # HLS segments
du -sh /var/www/peertube/storage/thumbnails/       # Video thumbnails
du -sh /var/www/peertube/storage/previews/         # Video previews
du -sh /var/www/peertube/storage/avatars/          # User/channel avatars
du -sh /var/www/peertube/storage/captions/         # Subtitle files

If PeerTube is configured to use S3/object storage, note the bucket names and credentials from your PeerTube production.yaml:

# PeerTube production.yaml - look for these sections
object_storage:
  enabled: true
  endpoint: 's3.us-east-1.amazonaws.com'
  region: 'us-east-1'
  credentials:
    access_key_id: '...'
    secret_access_key: '...'
  videos:
    bucket_name: 'peertube-videos'
  streaming_playlists:
    bucket_name: 'peertube-streaming'

Step 3: Choose a Migration Strategy​

Use Vidra's built-in Migration ETL API to connect directly to your PeerTube database and import data automatically.

When to use:

  • Your Vidra instance has network access to the PeerTube PostgreSQL database
  • You want a managed, auditable process with progress tracking
  • You want to dry-run before committing

Requirements:

  • PostgreSQL connection details for the PeerTube database
  • Network connectivity from Vidra to PeerTube's PostgreSQL port (default 5432)
  • Path or S3 access to PeerTube's media storage

Manual Migration​

Export PeerTube data with pg_dump, transform it with SQL scripts, and load it into Vidra's database.

When to use:

  • Network isolation prevents direct database access
  • You need to transform or filter data before import
  • Your PeerTube instance has significant customizations
  • You want full control over every step

Requirements:

  • SSH/terminal access to the PeerTube server
  • Ability to run pg_dump on the PeerTube database
  • A staging PostgreSQL instance for data transformation

Step 4: Prepare the Vidra Instance​

Before importing any data, your Vidra instance must be fully set up:

# 1. Ensure Vidra is running
docker compose up -d

# 2. Verify database migrations are current
make migrate-status

# 3. Apply any pending migrations
make migrate-up

# 4. Create an admin account (if not already done via setup wizard)
# Use the setup wizard at http://your-vidra-host:8080/setup/welcome
# Or the CLI:
./vidra-cli setup

Configure Storage Backend​

Vidra supports three storage backends. Choose the one that matches your operational needs:

BackendConfigurationBest For
LocalSTORAGE_PATH=/data/vidra/storageSingle-server deployments
S3S3_ENDPOINT, S3_BUCKET, S3_ACCESS_KEY, S3_SECRET_KEYScalable cloud deployments
IPFSIPFS_API_URL=http://ipfs:5001Decentralized distribution

Set the appropriate environment variables in your .env file before importing.

Step 5: Create a Rollback Plan​

Before starting the migration:

  1. Back up PeerTube completely:

    # Database
    pg_dump -Fc -d "$PEERTUBE_DATABASE_URL" -f peertube-backup-$(date +%Y%m%d).dump

    # Media storage
    tar czf peertube-storage-$(date +%Y%m%d).tar.gz /var/www/peertube/storage/

  2. Document your current DNS/proxy configuration so you can revert quickly

  3. Keep PeerTube running until migration is fully validated — don't shut it down early

  4. Set a go/no-go deadline — if validation fails by this time, roll back

Pre-Migration Checklist​

Use this checklist before proceeding to the actual migration:

  • PeerTube data inventory completed (user count, video count, storage size)
  • Vidra instance deployed and migrations applied
  • Admin account created on Vidra
  • Storage backend configured and tested (can write files)
  • Network connectivity verified (Vidra → PeerTube DB, if using API migration)
  • PeerTube database backed up
  • PeerTube media storage backed up
  • DNS/proxy rollback plan documented
  • Maintenance window communicated to users
  • Go/no-go deadline agreed

Next Steps​

Ready to proceed? Choose your migration path: