FolderView3 Migration

FolderView3 Migration

Version 2026.10.15.07 restores the coordinated FolderView3 preview for folders, rules, defaults, startup settings, and appearance. Migration is optional and replaces both folder types and saved preferences after confirmation.

Current release paths and limitation

Open Advanced -> Recovery -> Additional tools and choose Detect installed FolderView3 or Preview FolderView3 export. A complete version-1 backup selected in Basic Docker/VM Import or Recovery Import Environment is routed to this full migration. Setup Assistant accepts per-type exports and directs complete backups to Recovery. Older stable releases without these controls require updating first.

Keep the original full export and configuration directory. A normal full export omits icon/script files, native Docker autostart, and native organizer registry data; older exports may omit plugin startup settings too. Review warnings and verify those resources locally before removing the old plugin. Only one folder-rendering plugin should own runtime pages.

Before you begin

1. Copy the entire FolderView3 configuration directory off-server.
2. Copy /boot/config/plugins/folderview.plus too if FolderView Plus already contains data.
3. Keep the old export until every runtime surface is verified.
4. Open Settings -> FolderView Plus -> Advanced -> Recovery.

If FolderView3 is still installed, FolderView Plus may pause Docker/VM/Dashboard injection to avoid two folder runtimes owning the same host pages. Settings and migration review remain available. Do not remove FolderView Plus; remove the conflicting legacy plugin only after its data is safely copied and the migration plan is available.

Choose a source

• Detect installed FolderView3: reads the bounded FolderView3 configuration location and reports availability, version, and Docker/VM counts.
• Preview FolderView3 export: parses a supported full-export JSON file selected in the browser.

Detection and preview are read-only. Unsupported export schema versions are rejected rather than guessed.

What is converted

The preview can plan conversion of:

• Docker and VM folders, hierarchy, members, and stable member identities where available.
• Legacy folder regex into ordered auto-assignment rules.
• Docker and VM preferences and folder defaults.
• Dashboard layout preferences.
• FolderView3 custom start-order data into custom batches.
• Recognized appearance variables and bounded custom CSS into a named appearance profile.
• Informational counts for native Docker organizer/autostart data.

Imported appearance profiles, including reusable presets and styles from disabled directories, start inactive. The current active profile is retained. Notes, style toggles, and page preset/value assignments are retained as inert legacy recovery metadata available in a native environment export. Review before activating any imported CSS.

Saved order-docker.json and order-vm.json snapshots take priority over folder-record order. Missing or invalid snapshots fall back to configuration order. The preview reports duplicate or unknown references that were skipped. Positions of unassigned containers or VMs between folders on the native Unraid page are not imported.

Custom CSS retains its recognized Docker, VM, and Dashboard scopes, including filenames targeting several pages. Styles in .disabled directories become separate inactive profiles; unscoped CSS and generated theme files are excluded. Source metadata is informational and does not automatically enable managed updates. Scan the original source in Appearance if you want managed updates, and preview imported CSS before activation because selectors and variables can differ.

After migration, use Edit folder defaults under Docker or VMs in Settings to inspect or change the imported starting profile without creating a folder. Saving defaults affects future folders; applying them to existing folders requires the separate Apply to all action.

Assignment and preference compatibility

Migrated folders retain legacy ownership: explicit assignments anywhere take priority, then valid Docker labels, then regex in original source folder order. Display/startup placement uses saved folder order separately. Docker, VM, Dashboard, bulk actions, conflict reports, and Docker startup share this policy; native Plus rules retain their existing behavior. Imported existing folders receive effective inherited defaults while preserving explicit false/zero values, VM identity hints, and hidden preview choices.

Overflow values become default, expand row, or scroll. Preview reports unsupported Dashboard animation/update highlighting, disabled/direct-WebUI context modes, and color locking. Review converted/unsupported setting counts before applying.

Validation limits

Malformed required sections, unsupported versions, duplicate JSON keys, ambiguous names, and invalid expressions are rejected before writes; intentionally empty maps are supported. Full exports are limited to 5 MiB, 5,000 folders per type, 5,000 member/hidden/identity/action-target references per folder, 200 actions per folder, and 2,000 startup entries. Names allow 160 UTF-8 bytes per folder and 255 per member; regex allows 1,024 bytes. Appearance allows 32 total profiles, 128 stylesheets/2 MiB aggregate input, and 64 KiB per compiled layer. Over-limit input is rejected rather than truncated. Correct a copy and keep the original.

Review optional host changes

Replacing Unraid's native Docker autostart order is a separate, explicit option and defaults to off. The option is available only when source native-autostart entries exist. Review enablement and waits; the preview does not silently select replacement. FolderView3 organizer-registry data is also reported separately instead of automatically taking ownership of native host structures.

Custom CSS is bounded and scanned. Unsafe constructs such as remote @import rules are excluded and shown as warnings. Review all retained CSS before activating the imported appearance profile.

Preview digest and apply

The preview produces a digest of meaningful source and captured destination state; generated export timestamps do not invalidate an unchanged installed source. Apply requires confirmation and sends that expected digest back to the server. If the source changed or the preview is stale, reopen the preview rather than bypassing the check.

Apply performs one coordinated transaction:

1. Revalidates the source and expected digest.
2. Creates global and type-specific rollback protection.
3. Writes Docker, VM, rule, default, startup, and appearance targets using guarded per-file writes.
4. Optionally applies the separately selected native-autostart change.
5. Reads the saved state back and verifies it.
6. Rolls back if commit or verification fails.

Cancellation writes nothing. Apply checks source and destination again under the mutation lock. A successful apply refreshes Settings and Recovery; reload already-open Docker, VM, and Dashboard pages. Normal failures attempt automatic restoration and retain recovery evidence. A process kill or power loss cannot guarantee a multi-file atomic commit: after restart, restore the pre-migration global checkpoint and verify both types, appearance, and native startup together.

Logs records localized validation, stale-preview, capture, write, verification, and restoration outcomes. Diagnostics failure never determines whether a configuration write succeeds. Migration reports and raw backups are private recovery evidence; do not publish them as sanitized support bundles.

Screenshot placeholder — FolderView3 migration preview

Capture detected source/version, Docker/VM counts, operations, warnings, native-autostart opt-in shown off, digest status, and Apply confirmation using an isolated test system.

Verify the result

1. Confirm the transaction says Applied and verified.
2. Review Docker and VM folders in Basic Settings.
3. Open Rules and confirm converted regex priority.
4. Open Start Order and preview the sequence before synchronizing native order.
5. Open Appearance and review the inactive imported profile before activation.
6. Remove only the conflicting FolderView3 plugin when its external backup is secure.
7. Refresh Docker, VMs, and Dashboard and confirm the conflict-resolved banner.
8. Run Diagnostics and create a fresh manual snapshot.
9. Verify inherited settings, overflow, separators, update highlighting, hidden members, and returning/renamed VMs. Inspect inactive appearance and confirm icon/script files exist locally.
10. Verify persistence after navigation/reload. Check native startup during a planned maintenance window only after reviewing the intended order and enablement. These live-host checks are owner/tester acceptance; automated fixtures do not establish them.

When to use normal import instead

Use normal Docker/VM import when you only have one type file or want Merge/Add/Replace control for a narrow folder-map migration. Use this page's workflow when the source is a complete FolderView3 installation/export and coordinated conversion matters.

See also: Backup, Recovery, and Migration · Installation and Upgrades · Appearance, Icons, and Themes