Installation

Installation

Moonbase is a plugin for your media server, not an app on your devices. You install it once on the server, and every Moonfin app that connects to that server gets settings sync, Seerr, extra ratings, retro games and the rest. There are two flavours in one download page: a Jellyfin plugin that installs from a plugin catalogue and updates itself, and an Emby plugin that you drop into a folder.

If someone else runs your server, send them this page. Nothing here happens on a phone or TV.

Which one do I need?

Your server	Minimum version	Install method
Jellyfin	10.10 or newer	Plugin catalogue (recommended), or a zip by hand
Emby	4.8 or newer	A zip you extract into the plugins folder

Jellyfin

The easy way: the plugin catalogue

This route takes five clicks and keeps Moonbase updated like any other Jellyfin plugin.

1. Open the Jellyfin web page as an administrator and click your user icon at the top right, then Dashboard.
2. In the left menu open Plugins, then the Repositories tab.
3. Click the + button and fill in:
   • Repository Name: Moonbase
   • Repository URL: https://raw.githubusercontent.com/Moonfin-Client/Plugin/refs/heads/master/manifest.json
4. Click Save.
5. Switch to the Catalog tab, find Moonbase (it is in the General section), click it, and click Install. Leave the version on the newest one.
6. Restart Jellyfin: Dashboard > Restart at the top of the dashboard page, or restart the container or service.
7. Check it worked: Dashboard > Plugins > My Plugins shows Moonbase with the status Active.

Advanced: installing the zip by hand

1. Download the newest Moonfin.Server-<version>.zip from the Releases page.

2. Create a folder called Moonfin inside Jellyfin's plugins folder and extract the zip into it:

   Install type	Plugins folder
   Linux package	/var/lib/jellyfin/plugins/Moonfin/
   Docker	/config/plugins/Moonfin/ (inside the config volume)
   Windows	%ProgramData%\Jellyfin\Server\plugins\Moonfin\

3. On Linux make sure the files belong to the user Jellyfin runs as, for example sudo chown -R jellyfin:jellyfin /var/lib/jellyfin/plugins/Moonfin.

4. Restart Jellyfin.

A hand-installed copy doesn't update itself. Add the repository as well and the catalogue takes over from the next version.

Emby

The Emby plugin is a zip you extract, not a catalogue plugin.

1. Download the newest Moonfin.Emby-<version>.zip from the Releases page.

2. Extract it. You get Emby.Plugins.Moonfin.dll, SharpCompress.dll and a folder called web.

3. Copy all three into Emby's plugins folder, directly, not inside a subfolder:

   Install type	Plugins folder
   Linux package	/var/lib/emby/plugins/
   Docker	/config/plugins/ (inside the config volume)
   Windows	%AppData%\Emby-Server\programdata\plugins\

4. Restart Emby.

5. Check it worked: Dashboard > Plugins lists Moonbase.

The web folder must sit next to the dll. Without it the web app at /Moonfin/Web/ answers with a 404.

First things after installing

1. Turn on sync. Open the plugin page (Jellyfin: Dashboard > Plugins > My Plugins > Moonbase. Emby: Dashboard > Plugins > Moonbase), and on the General tab tick Enable Moonbase Sync, then Save. This is the master switch. Seerr and the ratings integrations don't work without it.
2. Open the web app. In a browser go to https://<your server address>/Moonfin/Web/, for example http://192.168.1.10:8096/Moonfin/Web/. On Jellyfin, if it is blank right after installing, run the Moonfin Startup task once under Dashboard > Scheduled Tasks and refresh the page.
3. Turn it on in your apps. In each Moonfin app go to Settings > Integrations > Moonbase Plugin and tick Enable Plugin. It should say the plugin was found. On Roku the menu is Settings > Moonfin Plugin.
4. Set up the rest at your own pace. The Admin Guide walks through every tab of the plugin page in plain words. Seerr has its own five-minute page, Seerr Setup.

Advanced: a Moonfin button in Jellyfin's own web header

On Jellyfin you can add a one-click Moonfin button to the stock web page header, next to SyncPlay, by installing the File Transformation plugin:

1. Add its repository the same way as above: https://www.iamparadox.dev/jellyfin/plugins/manifest.json
2. Install File Transformation from the catalogue and restart Jellyfin.
3. Force refresh your browser (Ctrl+F5, or Cmd+Shift+R on a Mac).

To hide the button while keeping the plugin, add this to Dashboard > General > Branding > Custom CSS:

.headerMoonfinButton { display: none !important; }

Emby has no equivalent injection path, so there is no header button there. The web app is still served at /Moonfin/Web/.

Updating

• Jellyfin, catalogue install: new versions show under Dashboard > Plugins > Catalog with an update marker, and Jellyfin's own Update Plugins scheduled task installs them. Restart Jellyfin after an update.
• Jellyfin, hand install: download the new zip and extract it over the old files, then restart.
• Emby: download the new zip, copy the three items over the old ones, restart Emby.

Your users' settings, Seerr sessions, themes and game saves are kept across updates. They live in a separate Moonfin folder, see Data Locations.

Uninstalling

• Jellyfin: Dashboard > Plugins > My Plugins > Moonbase > Uninstall, then restart.
• Emby: delete Emby.Plugins.Moonfin.dll, SharpCompress.dll and the web folder from the plugins folder, then restart.

Neither removes the data. To wipe everything, also delete the Moonfin folder under plugins/configurations/ and the plugin's XML file next to it. Data Locations lists both.