Migrating to Shoko Server: Step-by-Step Migration Checklist

Migrating to Shoko Server: Step-by-Step Migration Checklist

This checklist walks you through a reliable, low-risk migration to Shoko Server (media/anime library manager). Follow the steps in order and complete each task before moving on.

Before you start — prerequisites

• Backup: Keep full backups of source media files and any existing metadata/databases.
• Environment: Target machine meets Shoko Server system requirements (CPU, RAM, disk space).
• Network: Stable network access between source and target during migration.
• Accounts & Access: Admin access to source server(s), target server, and database (if applicable).
• Tools: SSH/SFTP client, rsync or similar, SQLite/MySQL tools if needed, text editor.

1. Plan your migration

1. Inventory media: Count files, total size, folder structure, naming patterns, and subtitle locations.
2. Decide migration method: Copy raw media and let Shoko re-scan, or attempt to migrate existing Shoko database and settings. (Default recommendation: copy media + let Shoko re-identify to avoid DB compatibility issues.)
3. Estimate downtime and time required: Scanning/identification can be CPU- and I/O-intensive—plan maintenance window.

2. Prepare the target server

1. Install Shoko Server: Follow official installation for your OS (Docker or native).
2. Configure storage: Create and mount directories for media and Shoko configuration/database. Ensure permissions allow the Shoko service user to read/write.
3. Set up database: If using external DB (MySQL/MariaDB/Postgres), create database and user; otherwise, ensure local DB storage location is ready.
4. Configure networking: Open required ports for WebUI and any remote access. Set up reverse proxy or TLS if needed.

3. Backup source data (essential)

1. Media files: Create a verified copy (e.g., rsync with –checksum or file-level copy + verification).
2. Shoko database/config: Stop source Shoko service and back up its database and config files. For SQLite, copy DB file; for MySQL, use mysqldump.
3. Other metadata: Export any external metadata or custom mappings you want to preserve.

4. Transfer media and optional DB

Option A — Media-only migration (recommended)

• Use rsync or equivalent to copy media to the target’s media folder:

  Code
  Copy CodeCopied
  rsync -avh –progress –partial –checksum /path/to/source_media/ user@target:/path/to/target_media/ 

• Verify file counts and sizes match.

Option B — Database migration (advanced)

• Stop both Shoko services. Transfer database dump or DB files.
• Import dump into target DB and update Shoko config to point to the restored DB.
• Be prepared to troubleshoot DB engine/version mismatches and path differences.

5. Configure Shoko on target to match your library layout

1. Media folders: In Shoko WebUI > Settings > Media Locations, add your media paths exactly as mounted on the target server.
2. Path mappings: If paths differ from source, set appropriate path mappings to preserve associations.
3. Hashing/identification settings: Choose whether to enable file hashing and similarity thresholds.
4. Metadata sources: Configure AniDB/TVDB or other metadata providers and confirm API keys if required.

6. Initial scan and identification

1. Start a full library scan: Monitor CPU, I/O, and database growth.
2. Watch logs: Check Shoko Server logs for errors on file access, permissions, or missing dependencies.
3. Resolve unmatched files: Use Shoko’s manual matching tools for files that fail automatic identification.

7. Validate library integrity

1. Spot-check matches: Open a representative sample of series/episodes to confirm correct metadata, artwork, and episode ordering.
2. Play media: Test playback via your client (e.g., Jellyfin, Emby, or direct) to ensure files are reachable and subs load.
3. Check collections, custom tags, and groups: Verify any custom organization carried over or re-created.

8. Migrate custom settings and automation

1. Scripts and plugins: Copy any automation scripts or plugins and adjust paths and credentials as needed.
2. Scheduled tasks: Recreate scheduled scans, backups, and maintenance tasks on the target.
3. Integrations: Reconnect integrations (notification services, remote indexers, reverse proxies).

9. Decommission or repurpose the source

1. Confirm completeness: Only after full validation, keep the source for a grace period (e.g., 7–14 days).
2. Final sync: Do a final rsync to capture any changes since the initial transfer.
3. Shutdown: Stop Shoko on source and, if desired, wipe or repurpose the machine per your retention policy.

10. Post-migration maintenance checklist

• Automated backups: Enable regular DB and config backups.
• Monitoring: Set resource monitoring for CPU, memory, disk, and database size.
• Performance tuning: Adjust Shoko cache, database indices, and scanning intervals.
• Documentation: Record new server paths, credentials, and any changed procedures.

Quick troubleshooting pointers

• Missing artwork/metadata: Verify metadata source credentials and re-run metadata fetch.
• Permission errors: Ensure Shoko service user owns media and DB files (chown/chmod).
• DB compatibility issues: Revert to media-only migration if DB import fails.

Completion criteria (you can use these as a final checklist)

• All media files transferred and verified.
• Shoko recognizes >95% of your library with correct matches or manually resolved items.
• Playback and integrations tested.
• Backups and scheduled tasks configured.
• Source server decommissioned after grace period.

If you want, I can generate rsync commands tailored to your source/target paths, or produce a migration checklist formatted as a printable one-page checklist.