-
Notifications
You must be signed in to change notification settings - Fork 38
Admin Guide
The Moonbase settings page, tab by tab, in plain words. You don't have to touch most of it. Sync alone already gives your users the biggest win, and everything else is optional.
Where the page is: Jellyfin: Dashboard > Plugins > My Plugins > Moonbase. Emby: Dashboard > Plugins > Moonbase. Both open the same page with the same tabs: General, Integrations, Games, Defaults, Themes, Messages, Actions, Syncs and Help. Click Save at the bottom after changing anything.
If you only do one thing on each tab:
| Tab | Do this |
|---|---|
| General | Tick Enable Moonbase Sync |
| Integrations | Paste a free MDBList API key and a free TMDB API key so your users get extra ratings without keys of their own. Add Seerr if you have it |
| Games | Skip unless you have ROMs |
| Defaults | Skip. Users decide for themselves |
| Themes | Skip |
| Messages | Skip |
Then Save, and tell your users to tick Settings > Integrations > Moonbase Plugin > Enable Plugin in their apps.
- Enable Moonbase Sync. The master switch. It turns on settings sync across devices and is required for the Seerr and ratings integrations. Leave it on.
-
Moonfin Web Client. Only matters for the web app at
/Moonfin/Web/.- Default Server URL pre-fills the Add Server box in the web app. Leave empty and it uses the address the page was opened from, which is right for nearly everyone.
-
Forced Server URL makes the web app connect to that address on load without asking. Use it when you want the web app to behave like a kiosk for one server. Use the base address, such as
http://192.168.1.10:8096, without/web. - Enable WebRTC Private Subnet Scan lets the web app look for servers on the local network. Turn it off if your browsers block WebRTC.
-
Enable client log upload. Lets your users send a diagnostic or crash report from the app with Send report to server. Reports land under Logs beside your server's own, named
upload_<client>_<version>_<time>.txt. This matters most on Emby, which has no way to receive one without this plugin. The apps strip server addresses, IP addresses and access tokens out before sending, each user is limited to 10 reports an hour at 1 MB each, and turning this off makes the button in the apps go grey.
Seerr Integration
- Enable Seerr and Seerr URL: the address of your Seerr, as your server sees it. The full walkthrough is Seerr Setup.
- Display Name: what the apps call it in menus, for example "Requests". Leave empty for "Seerr".
- Public Server URL: how Seerr reaches your server for notifications. Only needed when Seerr and the server can't reach each other by the server's own guess, typically separate Docker containers. See Seerr Notifications.
- Push Relay URL, Push Relay Key, Push Service Account: leave them alone. Phone notifications work through the hosted relay by default. They exist for people who run their own relay or Firebase project.
MDBList Integration
- Server-wide MDBList API Key: a free key from mdblist.com (Preferences > API Key). With it, every user sees Rotten Tomatoes, Metacritic, Letterboxd and other ratings in the apps without making their own account.
- Sync MDBList official lists and Max items per official list: turns MDBList's curated lists into home rows your users can switch on.
IMDb Charts
- Sync IMDb charts: adds IMDb Top 250, Popular and similar charts as optional home rows.
Recommendations
- Use Moonfin Recommends for similar items: replaces the server's "more like this" with Moonbase's own recommender. Jellyfin 12 or newer only.
Studio Logos
- Sync studio logos from TMDB and a refresh age. Downloads the studio logos the apps show on detail pages and caches them on the server.
TMDB Integration
- Server-wide TMDB API Key: a free key from themoviedb.org. Used for episode ratings, TMDB list rows and studio logos.
Each of these syncs runs as a scheduled task you can trigger by hand under Dashboard > Scheduled Tasks: Moonfin MDBList Ratings Sync, Moonfin MDBList Official Lists Sync, Moonfin IMDb Lists Sync, Moonfin Custom Lists Sync and Moonfin Studio Images Sync. Ratings appear after the first run, so run it once right after pasting a key rather than waiting for the schedule.
- Enable retro games switches the feature on. Everything is off until you do.
- Game libraries: tick the libraries that hold your ROMs.
- Emulator cores: games play out of the box from a public CDN. Install downloads the roughly 290 MB bundle onto your server so games work without reaching out, and Upload cores zip does the same from a file you provide.
Folder naming, box art, BIOS files, saves and per-platform support are on the Retro Games page.
The Default User Settings here are the starting point every user gets, split into the same sections the apps have: General Style, Details Screen, Navigation, Home Screen, Home Sections, Libraries, Playback, Extras and Integrations. Every control mirrors what the apps actually offer.
- A setting left on Not set (user decides) passes the user's own choice through. That is the right value for almost everything.
- A default only fills the gap. Anything a user has already changed on their own keeps their value, unless you push.
- Apply Defaults To Users (called Push Defaults To Existing Users on Emby, and found on the Actions tab) overwrites everyone's stored values with the defaults you set, and connected apps pick it up immediately. Use it deliberately.
Typical reasons to set a default: a house theme, the navigation position for a room full of TVs, a screensaver on TV clients, hiding the Seerr or Downloads button for a family server, or a sensible Max days in Next Up.
Uploaded Themes lists the custom themes on your server and lets you upload new ones. Themes are JSON files made in the built-in editor at https://<your server>/Moonfin/Web/theme/. The server checks each upload against the theme schema, so a broken file is refused rather than handed to clients. Connected apps see a new theme without restarting. Details on the Themes page.
Server messages are notes from you to your users that show up inside their apps, even if they were offline when you wrote them.
- Title, a Markdown body, a colour, an audience (everyone or selected users), optional start and end dates, and an optional link button.
- Saved Messages lists what you've written. Edit or delete from there.
- For a quick one-off with no scheduling, use Broadcast Message on the Actions tab instead.
Messages go out over the live connection and as a push notification to phones that have one registered. In the Moonfin apps they appear in a messages window with an unread badge. On Smart TVs they appear as an on-screen notice.
- Apply Defaults To Users (Jellyfin) or Push Defaults To Existing Users (Emby): see Defaults above.
- Broadcast Message: a one-off note to everyone right now.
- Web Plugin Status (Jellyfin): whether the File Transformation injection that puts the Moonfin button in Jellyfin's header is loaded. If it isn't, run the Moonfin Startup scheduled task once.
- Configuration backup: if the plugin ever finds itself running on default settings while a backup with your real settings is still on disk, a banner appears here with a Restore these settings button. Restart the server after restoring.
The Active Downloads dashboard: every transcoded download your users have running, with live transcode metrics. Useful to see who is making the server work before the first byte reaches their device.
Links to the docs, the header button instructions for Jellyfin, and on Emby a reminder that the web app is opened directly at /Moonfin/Web/.
All of these live under Dashboard > Scheduled Tasks and can be run by hand:
| Task | What it does |
|---|---|
| Moonfin Startup | Registers the Jellyfin header button injection. Normally automatic. Run it once if the web app or the header button doesn't load after installing |
| Moonfin Settings File Repair | Checks every user's settings file and repairs or quarantines damaged ones. Runs at startup on its own |
| Moonfin MDBList Ratings Sync | Fetches ratings for your library from MDBList |
| Moonfin MDBList Official Lists Sync | Refreshes the MDBList list rows |
| Moonfin IMDb Lists Sync | Refreshes the IMDb chart rows |
| Moonfin Custom Lists Sync | Refreshes custom rows built from MDBList and IMDb lists |
| Moonfin Studio Images Sync | Downloads studio logos from TMDB |
Almost everything works the same on both servers. The differences:
| Feature | Jellyfin | Emby |
|---|---|---|
| Moonfin button in the server's own web header | Yes, with the File Transformation plugin | No, Emby has no way to inject it. Open /Moonfin/Web/ directly |
| Audiobook bookmarks and notes synced through the server | Yes | No |
| Moonfin Recommends for similar items | Jellyfin 12 and newer | No |
| Settings File Repair | Scheduled task | Runs at startup automatically, plus a manual task |
| Client log upload from the apps ("Send report to server") | Yes, Jellyfin has its own endpoint, so the plugin isn't needed | Yes, but only through this plugin, since Emby has no endpoint for it. Needs Enable client log upload |
| Everything else: sync, Seerr, notifications, ratings, list rows, retro games with saves and self-hosted cores, themes, messages, collection ordering, active downloads | Yes | Yes |
User settings, Seerr sessions, themes, saves and caches are in a Moonfin folder under your server's plugin configuration directory. Your own choices from this page are in an XML file next to it. Both, with backup and reset advice, are on Data Locations.
For server admins
Reference
For developers