Installation and Upgrades

Installation and Upgrades

FolderView Plus supports Unraid 7.0.0 or newer. Use the stable branch for normal operation and dev only when testing an unreleased change.

Install the stable release

Open Plugins -> Install Plugin and enter:

plugin install https://raw.githubusercontent.com/alexphillips-dev/FolderView-Plus/main/folderview.plus.plg

The command can also run in an Unraid terminal. After installation, open Settings -> FolderView Plus.

Install the development build

Use this only for directed testing:

plugin install https://raw.githubusercontent.com/alexphillips-dev/FolderView-Plus/dev/folderview.plus.plg

The installed manifest retains its branch-specific update URL. Reinstall the stable main manifest when testing ends.

Understand the installation report

The final FolderView Plus report distinguishes installation, upgrade, reinstall, and downgrade. It reports core package state, previous/current versions, icon-pack verification and activation, preserved or initialized configuration, scheduled-backup registration, elapsed time, and a recommended next action.

A failed stage reports the stage and exit code instead of printing a success summary. Save that output for support.

Screenshot placeholder — successful installation report

Capture the final FolderView Plus report after a stable installation. Redact server name, IP addresses, private mirror URLs, and terminal history outside the command/output.

Normal updates

1. Create a recovery snapshot before large behavior changes.
2. Open Plugins -> Check for Updates.
3. Install the available FolderView Plus update.
4. Reload affected pages. Use Ctrl+F5 if stale JavaScript or CSS is suspected.
5. Verify Settings, Docker, VMs, Dashboard, privacy choices, custom icons, rules, and start order.

A normal update replaces runtime files under /usr/local/emhttp/plugins/folderview.plus and preserves persistent configuration under /boot/config/plugins/folderview.plus.

Settings also provides an in-plugin update check that reports installed/remote versions, manifest source, request status, and timing. The What Changed panel shows categorized notes for the installed version and can be dismissed without changing the installation.

Force-refresh helper

The development update tools can prepare a maintainer-directed force-refresh install script. It removes cached folderview.plus-*.txz package files, downloads a cache-busted copy of the configured manifest, runs installplg, and prints the installed version.

This is not a routine update path. Use it only when a maintainer is diagnosing a stale development manifest/package cache, review the generated manifest URL, and copy the persistent plugin directory first when recovery risk exists.

“Not reinstalling same version”

Unraid does not reinstall a manifest with the same version as the installed plugin. Confirm the installed version and whether its manifest tracks main or dev, then check for an actually newer manifest. Do not edit the installed version file to bypass comparison.

For a maintainer-directed commit test:

plugin install https://raw.githubusercontent.com/alexphillips-dev/FolderView-Plus/<commit>/folderview.plus.plg

Return to the normal branch URL afterward. The package referenced by that commit must still exist.

Icon asset pack

The large third-party icon library is versioned separately from the core package.

Purpose	Location
Persistent verified archive	/boot/config/plugins/folderview.plus/folderview.plus-icons-<version>.txz
Active RAM cache	/tmp/folderview.plus-assets/icons-<version>
Runtime link	/usr/local/emhttp/plugins/folderview.plus/images/third-party-icons

Reboot clears the RAM cache; installation recreates it from the persistent verified archive. A core update normally reuses an unchanged icon pack.

USB replacement or restore

1. Restore /boot/config/plugins/folderview.plus from the USB backup.
2. Install the correct stable or dev manifest.
3. Allow icon-pack verification and activation to finish.
4. Run Advanced -> Diagnostics.
5. Verify folders before importing or restoring anything else.

If the plugin directory was not backed up, use an external FolderView Plus export for the configuration it contains. Local snapshots cannot help if their entire directory was lost, and environment export does not contain uploaded custom-icon binaries or saved folder-template files.

Legacy Folder View conflicts

FolderView Plus detects active Folder View 2 and Folder View 3 installations. To prevent two runtimes from modifying the same pages, it pauses FolderView Plus injection on Docker, VMs, and Dashboard while keeping Settings, backups, migration, and conflict guidance available.

Recovery sequence:

1. Keep FolderView Plus installed.
2. Back up the old plugin's configuration.
3. Preview/apply migration where needed.
4. Remove only the detected conflicting Folder View 2/3 plugin.
5. Refresh the webGUI.
6. Confirm the conflict-resolved banner and verify Docker, VMs, and Dashboard.

This conflict pause is different from native-Docker safe mode, which protects an unknown/future Unraid host surface.

Screenshot placeholder — legacy conflict banner

Capture the paused-runtime guidance and resolved banner on an isolated test system with no server identity.

Downgrades

Older releases may ignore or normalize newer fields. Before downgrading, export the environment, copy the persistent plugin directory off-server, review intervening release notes, and avoid extensive saves until behavior is verified. Returning to the latest release and restoring the pre-downgrade export is safer than hand-editing JSON.

Uninstall

Copy the entire /boot/config/plugins/folderview.plus directory off-server before uninstalling. An environment export alone is not a complete backup. The remove action deletes:

• Docker and VM folder configuration and preferences.
• Local backups, rollback snapshots, and change history.
• Uploaded icons and custom styles/scripts.
• The persistent icon-pack archive and runtime cache.
• Scheduled-backup registration.

Docker containers, VMs, and their application data are not deleted. FolderView Plus organization and recovery data are deleted.

Post-update checklist

• Expected plugin version appears in Plugins.
• Settings loads without a fatal diagnostic banner.
• Docker, VMs, and Dashboard render the expected folders.
• Custom icons and theme overrides load.
• Diagnostics reports the installed runtime as intact.
• Scheduled backup registration is present when enabled.

See also: Security and Package Trust · Troubleshooting