HarborFM

Admin and Settings

Guides for instance administrators: global settings, user management, SSO, and troubleshooting.

Global Settings

Admins have access to a Settings page that controls instance-wide behavior. The page uses a tabbed layout: each section (Access & General, Default Limits, Final Output, Integrations, etc.) is a tab. The first tab is System (version, command status, memory/CPU/disk from the system-stats API). A global search box filters tabs and scrolls to matching controls (e.g. typing "Account Registration" jumps to Enable Account Registration). There is a single form and one Save button across all tabs. On desktop you see a vertical sidebar for tabs; on mobile, a drawer. You can use keyboard navigation (arrow keys, Home/End to jump to first/last tab, Escape to close the drawer).

Key areas (in their respective tabs):

System

The System tab shows instance version, command status, and system stats (memory, CPU, disk). Use it for a quick health check.

Account and Access

  • Account registration - Enable or disable whether new users can create accounts.
  • Public feeds - Enable or disable public podcast and episode pages and RSS feeds for listeners.
  • White Label - Optional name that replaces "HarborFM" on public feed headers, episode pages, share titles, embed players, and related public surfaces when configured.
  • Welcome banner - Optional message shown to users (e.g. on login or dashboard).
  • Hostname - Set the public hostname so SSO callbacks, WebRTC public WebSocket URL, and related links stay correct. Changing Hostname updates the WebRTC public WebSocket URL when it still pointed at the previous host. Once set in WebRTC Settings, those values take precedence over WEBRTC_* env vars.

Defaults and Limits

  • Default limits for new users - Max podcasts, max episodes, max storage per user when they sign up. Can be overridden per user in User management.
  • defaultCanStripe - Whether newly registered users get Stripe Payments access. Default is on. See Stripe payments.
  • defaultCanImportTheme - Whether newly registered users can import and edit page themes. Default is on.

Episode Output

  • Final Episode Output - Default format for rendered episodes (e.g. mono vs stereo, bitrate). Affects Build Final Episode output.

Integrations

  • GeoLite2 - MaxMind GeoIP for analytics (country/city). Configure GeoIP credentials and update path if used. See Analytics.
  • Whisper ASR - URL and options for the Whisper service used to generate transcripts. When set, users can generate transcripts in the episode editor.
  • LLMs - Ollama or OpenAI (or compatible) endpoint and API key for segment transcript helpers. When set, users can "ask" the LLM about a segment. Also used for optional review spam checks when enabled.
  • Captcha - reCAPTCHA or hCaptcha for registration, login, or public polls/reviews if enabled.
  • Email - SMTP (or SendGrid etc.) for password reset, verification, invite emails, review verification, and Stripe token recovery / receipts when configured.

Changes are saved from the Settings page. Some options require environment variables; see the main README ("Docker environment variables") and Deployment: Environment variables.

See Also

User Management

Admins can view and manage users from the Users page.

User List

  • View all users on the instance.
  • For each user you can typically see: email, username, role (admin or not), account status (enabled/disabled), and optionally storage or usage.

Per-User Actions

  • Podcasts - View the list of podcasts owned by or shared with that user.
  • Library - View the user's library (and optionally storage used).
  • Edit - Change email, username, or other profile fields; change password (set a new password for the user); disable or enable the account.
  • Limits - Set or override max podcasts, max episodes, and max storage for that user. If they hit a limit (e.g. storage), actions like Record new section may be disabled until the limit is raised or they free space.
  • canStripe - Per-user flag for Stripe Payments. When off, that user cannot open Stripe Payments or call Stripe API routes (403). Independent of show role. See Stripe payments.
  • canImportTheme - Per-user flag for page themes. When off, that user cannot import, download, or edit theme packages (403). Selecting a server-wide theme on a show they manage still works. See Page themes.
  • Video generation - Per-user permission (canGenerateVideo) when the instance allows video generation.

Invite to Platform

When inviting a collaborator to a show, if the person doesn't have an account yet, the UI can send an "invite to the platform" email (rate-limited per inviter per day). Admins can also invite users directly if the instance supports it.

See Also

SSO (OIDC / SAML)

HarborFM supports Single Sign-On via OIDC (OpenID Connect) and SAML. Configured providers appear as sign-in options on the login page. Add and edit providers under Settings > SSO (OIDC / SAML).

General

  • Set the Hostname (e.g. app.harborfm.com or https://app.harborfm.com) so callback URLs are correct.
  • Use "(set)" in password or certificate fields when editing a provider to keep existing secrets without re-entering them.

OIDC (E.g. Keycloak, Google, Auth0)

  1. In your identity provider (IdP), create a client and note the Client ID, Client secret, and redirect/callback URL. The callback URL in HarborFM is typically https://your-host/api/auth/sso/oidc/callback/{provider-id}.
  2. In HarborFM, under OIDC providers, click Add Provider.
  3. Set Provider ID (slug used in the callback path), Display name, Discovery URL (e.g. https://keycloak.example.com/realms/harborfm for Keycloak - no path suffix; HarborFM fetches /.well-known/openid-configuration), Client ID, Client secret, and Scopes (e.g. openid profile email).
  4. Enable Trust email from provider if you want account linking by email.
  5. If you see "issuer does not match," set Issuer Override to the exact issuer from your IdP's /.well-known/openid-configuration.

Save the provider, then Save at the bottom of Settings.

SAML (E.g. Keycloak)

  1. In the IdP, create a SAML client. Set Client ID (entity ID) to HarborFM's SAML entity ID: https://your-host/api/auth/sso/saml. Set Valid redirect URIs (ACS URL) to https://your-host/api/auth/sso/saml/callback/{provider-id}.
  2. From the IdP, get the IdP certificate (PEM) and IdP Entry Point URL (SAML login URL).
  3. In HarborFM, under SAML providers, click Add Provider. Enter Provider ID, Display name, IdP Entry Point URL, IdP certificate (PEM). Optionally configure SP certificate/private key if the IdP requires signed requests.
  4. Use the Callback URL shown in the form when configuring the IdP.

Full step-by-step for Keycloak (OIDC and SAML) is in the main README ("Single Sign-On (SSO)").

See Also

Troubleshooting

Common issues and where to look. For full detail, see the main README ("Troubleshooting" and related sections).

Setup URL / "Server Not Set Up Yet"

On first run, the one-time setup URL is printed in the server (or container) logs. Open that URL in your browser (e.g. https://your-host/setup?id=...) to create the admin account.

  • Lost the URL? Restart the server to see it again. The token is regenerated only if the secrets file is missing.
  • Where to look: docker logs <container>, or the terminal where you ran pnpm run dev or the server process.

See Getting started.

Ffmpeg or Audiowaveform Not Found

The server needs ffmpeg and audiowaveform for segment processing (trim, concat, silence removal, waveforms).

  • Docker: The official image includes ffmpeg. If you use a custom image or run locally, ensure both are installed and on the PATH.
  • Local dev: Install via your package manager. For audiowaveform, build from source or use a package if available (e.g. on macOS: brew install audiowaveform).

You can override binary paths with environment variables; see main README (FFMPEG_PATH, FFPROBE_PATH, AUDIOWAVEFORM_PATH).

Group Calls Not Working

  • No "Record" or group-call UI - Ensure WebRTC is enabled: WEBRTC_ENABLED=1, and that WEBRTC_SERVICE_URL and WEBRTC_PUBLIC_WS_URL are set (or configured under WebRTC Settings after Hostname is set). See main README "WebRTC (group calls)."
  • Can't connect / no audio - Verify firewall allows UDP ports (default 40000–40200, or 41000–41100 in Docker). Behind NAT, set MEDIASOUP_ANNOUNCED_IP to the server's public IP.
  • Stale WebSocket URL after domain change - Confirm Hostname and WebRTC Settings still match the public host.
  • Logs: docker compose logs webrtc or pm2 logs webrtc.

See Group calls.

Login Failures and IP Bans

Repeated failed login attempts can trigger a temporary IP ban. The main README documents LOGIN_FAILURE_THRESHOLD, LOGIN_BAN_MINUTES, and LOGIN_WINDOW_MINUTES. Admins can clear IP bans (e.g. via server script pnpm run db:clear-ip-bans or equivalent; see README "Scripts").

Backup and Upgrading

Before upgrading, back up DATA_DIR (database, uploads, processed audio, RSS, artwork, library). Optionally back up SECRETS_DIR. Migrations run automatically on server start. See main README "Backup and upgrading."

See Also