Skip to content

Getting started

Get Tuvima Library running, create your administrator account, and open the Dashboard. Docker configuration takes about 10 minutes; image downloads and optional AI models can take longer.

Choose an installation

Your setupStart here
Docker host or Docker DesktopDocker Compose, the recommended starting path
Synology, Unraid, TrueNAS SCALE, or QNAPSynology, Unraid, TrueNAS, or QNAP
Windows 10 or 11 PCWindows installer (Early Access)
Development or source evaluationRun from source

Start with Docker

  1. Install Docker with Compose.

  2. Download the maintained configuration in a new deployment folder:

    Terminal window
    curl -fsSL https://raw.githubusercontent.com/Tuvima/tuvima-library/main/docker-compose.yml -o docker-compose.yml

    In PowerShell:

    Terminal window
    Invoke-WebRequest https://raw.githubusercontent.com/Tuvima/tuvima-library/main/docker-compose.yml -OutFile docker-compose.yml

  3. Edit every host folder under volumes, then set your user/group IDs and timezone. The Docker guide explains permissions and origins.

  4. Keep all seven persistent mounts:

    MountContents
    /libraryManaged media
    /configSettings and credentials
    /dbCatalogue
    /modelsOptional AI models
    /artwork-cacheArtwork, cache, and logs
    /backupsRecovery archives
    /transcodePrepared playback files

  5. Start Tuvima:

    Terminal window
    docker compose config --quiet
    docker compose pull
    docker compose up -d
    docker compose ps

  6. Open http://SERVER-IP:5016/setup. Use localhost only from the Docker host itself.

If the image download is refused, build the image from source and continue with account setup below.

Only the Dashboard is published. Leave Engine port 61495 internal.

You can add the Dashboard to your home screen or install it as an app from your browser’s menu. Browsers offer installation only over HTTPS or from localhost, so a plain http://SERVER-IP:5016 address may not show the option. An installed copy opens in its own window and reconnects when the server is reachable; it does not keep a copy of your library offline.

The setup steps

Setup has six steps. A side list shows where you are, and you can go back at any time.

  1. Name your server. Pick a friendly name that phones, TVs and other computers can find. A quick server check runs silently after this; if it fails you see one plain message and a Retry button. Restore a backup is offered on this first screen if you are moving from another server.
  2. Your account. Create the administrator (see below).
  3. Libraries. Choose a media type and add the folders it lives in, or Skip for now. You can also set an Import folder here. Nothing is required.
  4. Language. Display language, metadata language and country.
  5. Enhance your library. Optional providers. The one button reads Skip for now until you enter something, then Continue.
  6. All set.

Tuvima’s own library folder is created for you under the server’s data location (TUVIMA_DATA_DIR, otherwise your per-user local data folder). You are never asked about it.

Create your administrator

  1. Finish setup before you open any router port: until the administrator exists, anyone who can reach the server can claim it.
  2. Enter an email and password for your administrator account.
  3. Choose a separate profile display name and an optional profile PIN.
  4. Save the recovery codes in a password manager or another safe place outside this server.
  5. Continue through setup. Media folders and provider connections can be added later.

Setup needs no code from any device on your home network (see Claim your server). Once the account exists, setup requires administrator sign-in. Profile PINs and administrator unlock are separate from your account password.

Choose your first media

Use the Libraries step, or later Settings → Libraries, for books, comics, movies, TV, music, and audiobooks. Start with a few files so you can check matching and folder permissions.

For private photos, home videos, or documents, use View Personal Space. Those files follow a local path without catalogue providers.

The default Standard AI profile uses one 1,260 MB text model. The separate 1,500 MB Whisper audio pack starts disabled. You can begin library setup while downloads run or AI features remain disabled.

Next steps