Skip to content

Admin and settings

Jump to bottom
Logan Rickert edited this page Feb 21, 2026 · 4 revisions

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.
  • Welcome banner - Optional message shown to users (e.g. on login or dashboard).

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.

Episode output

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

Integrations

  • GeoLite2 - MaxMind GeoIP for analytics (country/city). Configure GeoIP credentials and update path if used.
  • 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.
  • Captcha - reCAPTCHA or hCaptcha for registration or login if enabled.
  • Email - SMTP (or SendGrid etc.) for password reset, verification, and "invite to platform" emails.

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.

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. 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.
  • 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

Clone this wiki locally