Skip to content

First Run

Jump to bottom
Brandon Johnson edited this page Sep 7, 2026 · 4 revisions

First Run

Everything in Obelo is authenticated — there is no anonymous mode and no default password. The very first admin account is bootstrapped with a one-time claim token printed to the server's log.

1. Find the claim token

On first start, while the database has no users, the server prints:

obelo: no users yet — first-Admin claim token: <token>
obelo: complete setup via POST /api/v1/setup with this claimToken

With Docker:

docker logs obelo

If you missed it and have not completed setup yet, just restart — the token is printed again on every start until the first user exists.

2. Create your admin account

Open the web app (http://localhost:8080, or the server's LAN address). The setup wizard asks for the token, then for the username and password you want.

Once the first admin exists, setup permanently closes — the endpoint stops accepting claims and the token stops being printed. Every later user is created by an admin from the users screen.

3. Create your libraries

A library holds one media kind — Movies, TV, or Music — and is backed by one or more folders on disk. Multiple folders merge into a single library, so /media/movies and /media/movies-4k can be one "Movies" library.

Point each library at the paths as the server sees them. In Docker that is the container path (/media/movies), not the host path (/srv/media/movies). This is the single most common first-run mistake.

4. Scan

Trigger a scan from the library. What happens:

  • The scanner walks the folders, and works out what each file is from its path and embedded tags — not from a cloud lookup. This is why naming matters, and why your library stays correct offline. See docs/naming-convention.md for what the parser expects.
  • ffprobe reads each file's streams to decide how it can be played later.
  • Scans are incremental, so re-scanning an unchanged library is cheap. One runs on a schedule (OBELO_SCAN_INTERVAL, default hourly) as a safety net.
  • Files that disappear are soft-deleted — if a drive was unmounted and comes back, so does your watch state.

5. Turn on enrichment (optional)

Obelo is offline-first. Out of the box it makes zero outbound calls and every title shows as un-enriched — correct, just unadorned.

To get posters, backgrounds, cast, descriptions and artist biographies, you grant enrichment consent and configure at least one provider in the admin settings:

  • Movies and TV need a TMDB API key (free, from themoviedb.org).
  • Music needs only MusicBrainz turned on — no key. fanart.tv and TheAudioDB keys add artist imagery and biographies on top.

Consent is a real gate, not a formality: an unconsented server makes no enrichment calls regardless of what keys are present.

External metadata only ever decorates. It never decides what a file is, so a wrong match is a cosmetic problem you can correct — and correcting it does not change your library's identity or your watch state.

6. Add users and devices

  • Create per-user accounts with their own library access, content-rating ceilings, and private watch state.
  • Native clients get named per-device tokens you can revoke individually — so losing a tablet does not mean changing everyone's password.
  • TVs sign in with a device code rather than typing a password on a remote.
  • One row on that screen is not a person: a Linked server is the role you give a friend's Obelo when you lend it a library. It has no password and no watch state — see Linked Servers.

Where to go next

Obelo

Home

Getting started

Reference

Going further

Plugins

Sharing with another household

Reaching it from away

When it breaks

Clone this wiki locally