Skip to content

Latest commit

 

History

History
436 lines (278 loc) · 32.1 KB

installation.md

File metadata and controls

436 lines (278 loc) · 32.1 KB

Installing Kalinka

Kalinka has three parts. They can all run on one machine or be spread across several, as long as they are on the same home network:

  • The server keeps your music library and the play queue. You need one, running all the time.
  • An output (the renderer) plays the sound. It runs on the machine your DAC, amplifier or speakers are plugged into. The server's machine gets one, and you can add more.
  • A remote is what you control it from: the Kalinka app (Android, Windows, Linux) or any web browser.

The steps:

  1. Install the server.
  2. Connect it to your network, if it is not on a cable.
  3. Open Kalinka in the app or a browser, and follow the setup it shows.
  4. Put your music on it.
  5. Add more outputs, if you want music in more than one room.

Install the server

What you have What to do
A Raspberry Pi 3, 4, 400, 5 or Zero 2 W A. Flash the Raspberry Pi image
A spare 64-bit PC, mini-PC or thin client B. Flash the PC image
A home server that runs virtual machines C. Run the PC image as a virtual machine
A computer already running Debian 13, Raspberry Pi OS (64-bit, Trixie), DietPi or Ubuntu 26.04 D. Install with one command

If you are not sure, use an image. It is a complete system with Kalinka and the supervisor already installed, and needs no typing.

Kalinka needs a 64-bit system. Playback and the library run in 512 MB of memory; 1 GB is comfortable. Smart search needs 2 GB or more, so leave it off on a Pi 3 or Zero 2 W. See the requirements.

A. Raspberry Pi image

You need:

  • a Raspberry Pi 3, 4, 400, 5 or Zero 2 W, or a Compute Module 3, 4 or 5, and its power supply;
  • a microSD card or USB SSD of 8 GB or more. Everything on it is erased. Kalinka uses the whole card, so take a bigger one if you will keep music on it;
  • a computer with a card reader;
  • a DAC HAT or a USB DAC. The Pi's HDMI and, on a Pi 3 or 4, its headphone socket work too;
  • a network cable, if you can. Otherwise give Imager your Wi-Fi in step 5, or set it up after the first start.

1. Download the image

Open the Kalinka image releases. In the newest one, under Assets, download the file that ends in:

  • -rpi5-arm64.img.xz for a Raspberry Pi 5, 500 or CM5;
  • -rpi234-arm64.img.xz for any other Pi.

With a screen on the Pi, take -rpi5-display-arm64.img.xz or -rpi234-display-arm64.img.xz instead. It is the same player, with a now-playing screen (cover, track, touch controls) switched on from the first start. You can turn it off in the app later.

The file is about 450 MB. Do not unpack it.

2. Write it to the card

  1. Install Raspberry Pi Imager on your computer and put the card in.
  2. In Imager, choose your Pi model.
  3. For the operating system, scroll to the bottom of the list, choose Use custom, and pick the file you downloaded.
  4. Choose your card. Check its name and size: whatever you pick is erased.
  5. When Imager offers to customise the card, fill in your Wi-Fi, a host name, a login and your time zone here, and turn on SSH if you want to log in to the streamer. Kalinka applies them at the first start, as Settings on the card describes. You can also leave them out.
  6. Write, and wait until Imager has finished verifying.

balenaEtcher works too: Flash from file, Select target, Flash! It offers none of these settings, but you can still give the streamer your Wi-Fi, a login and SSH with Raspberry Pi OS's own files, as Settings on the card describes.

There is nothing else to change on the card. A DAC HAT without an ID chip is set up after the first start, and so is Wi-Fi if you did not give it to Imager.

3. Switch it on

Put the card in the Pi, connect your DAC and the network cable, and plug in the power. The first start takes a couple of minutes.

Then connect it to your network if it has neither a cable nor the Wi-Fi you gave Imager, or go straight to Open Kalinka.

B. PC image

This turns a spare PC into a Kalinka player. You write the image to a USB stick or USB disk and start the PC from it. The PC's own disk is not touched.

You need: a 64-bit Intel or AMD PC, a USB stick or disk of 8 GB or more (it is erased; a small USB SSD lasts longer than a cheap stick), and a network cable if you can.

  1. Download the file that ends in -amd64.img.xz from the image releases. Do not unpack it.
  2. Write it to the USB stick with balenaEtcher or Raspberry Pi Imager (Use custom, as in option A, but without its settings: the PC image does not support them).
  3. Start the PC from the stick. Switch the PC on, press the boot menu key straight away (usually F12, F11, F10, F8 or Esc) and choose the USB drive. Secure Boot can stay on. To start from it every time, put USB first in the boot order.
  4. The first start takes a couple of minutes. Then connect it to your network if it has no cable, or go straight to Open Kalinka.
Put Kalinka on the PC's internal disk instead

This erases the internal disk. Start the PC from any Linux live USB stick, download the image there, and write it to the internal disk. Replace /dev/sdX with that disk; lsblk lists the disks.

xzcat kalinka-*-amd64.img.xz | sudo dd of=/dev/sdX bs=4M conv=fsync status=progress

Remove the live stick and restart. Kalinka grows to fill the disk on its first start.

C. Virtual machine

The PC image also runs as a virtual machine, which suits a home server that is on all the time anyway. Four things matter:

  • Bridged network, not NAT. Your phone has to reach the VM directly. Use a Bridged Adapter in VirtualBox, a bridge in virt-manager, vmbr0 in Proxmox, or an External switch in Hyper-V.
  • UEFI or BIOS firmware. The image starts with either, and with Secure Boot on.
  • A bigger disk. The image is 8 GiB. Make the virtual disk 16 GB or more before the first start, more if the music will live inside the VM.
  • 2 CPU cores and 2 GB of memory, or 4 GB for smart search.

A VM usually cannot reach your DAC. Let the VM be the server, and add an output on a small streamer next to your amplifier. You can also pass a USB DAC through to the VM.

1. Download and unpack the file that ends in -amd64.img.xz from the image releases. On Linux or macOS run xz -d kalinka-*-amd64.img.xz; on Windows, use 7-Zip. You get a .img file.

2. Import it. Replace kalinka.img with the name of your file:

Software How
virt-manager / QEMU qemu-img convert -f raw -O qcow2 kalinka.img kalinka.qcow2, then qemu-img resize kalinka.qcow2 32G. Create a VM with Import existing disk image and choose Debian 13.
Proxmox VE Create a VM with no disk, then on the host run qm disk import <vm-id> kalinka.img local-lvm. Attach the imported disk, make it the boot disk, and resize it under Hardware.
VirtualBox VBoxManage convertfromraw kalinka.img kalinka.vdi --format VDI, then VBoxManage modifymedium disk kalinka.vdi --resize 32768. Create a Linux / Debian (64-bit) VM with this disk and set the network to Bridged Adapter.
Hyper-V qemu-img convert -f raw -O vhdx kalinka.img kalinka.vhdx. Create a Generation 2 VM with this disk, and under Security set the Secure Boot template to Microsoft UEFI Certificate Authority.

3. Start the VM, give it a few minutes, and go on to Open Kalinka.

D. Install with one command

Use this on a computer that already runs one of these 64-bit systems:

  • Debian 13 (trixie)
  • Raspberry Pi OS (64-bit) based on Debian 13 (trixie). The older Bookworm release gets the server but no sound output.
  • DietPi on Debian 13
  • Ubuntu 26.04 LTS. Ubuntu 24.04 has no renderer package: its libraries are older than the renderer needs.

The server needs Python 3.11 or newer, which all of these have: on an older system, such as Ubuntu 22.04, the script stops before it downloads anything.

cat /etc/os-release tells you which one you have. Open a terminal on that computer, or log in to it over SSH, and run:

sudo apt install -y ca-certificates curl python3
curl -fsSL https://kalinkaplayer.com/install.sh | sudo bash

On a Debian system without sudo, log in as root and run the same commands without it.

This installs the server, its plugins, the browser player and an output for this computer's own sound card. Everything starts straight away and again after every restart. The first start downloads more components, so it needs the internet and takes a few minutes. Then go on to Open Kalinka.

It does not install the supervisor. Add it if you want the control page, Wi-Fi setup without a cable, or to set up a DAC HAT from the app.

If the computer runs a firewall, let your home network reach TCP port 8000 (and 8001 for the supervisor) and mDNS on UDP port 5353.

Starting from a blank Raspberry Pi
  1. In Raspberry Pi Imager, choose your Pi, then Raspberry Pi OS (other) → Raspberry Pi OS Lite (64-bit), then your card.
  2. When Imager offers settings, set a host name (for example kalinka), a user name and password, your Wi-Fi if you need it, and turn on SSH.
  3. Write the card, start the Pi, and log in from your computer: ssh <your-user>@kalinka.local.
  4. For a DAC HAT without an ID chip, set it up as its maker describes. This is usually one dtoverlay= line in /boot/firmware/config.txt, followed by a restart. With the supervisor installed, the app can do this instead.
  5. Run the install command above.
A screen on this machine

On a Raspberry Pi with a screen, install the now-playing display with the rest:

curl -fsSL https://kalinkaplayer.com/install.sh | sudo KALINKA_DISPLAY=1 bash

Restart when the script says so, then switch on Now-playing display on this machine in the app's advanced settings.

Reading the script first
curl -fsSL https://kalinkaplayer.com/install.sh -o install.sh
less install.sh
sudo bash install.sh

Running it again later upgrades whatever is installed.

Fedora

Fedora 44 gets the server and the output, but not the browser player, the supervisor or automatic updates. Download kalinka-server-…noarch.rpm from the latest server release, then:

sudo dnf install ./kalinka-server-*.noarch.rpm
curl -fsSL https://kalinkaplayer.com/install-renderer.sh | sudo bash

To upgrade, install the newer .rpm the same way.

Connect your streamer to the network

With a network cable, there is nothing to do: plug it into your router before switching the streamer on.

With the Wi-Fi you gave Raspberry Pi Imager, a Raspberry Pi joins it by itself at its first start. If it cannot, it opens the setup network below instead, two or three minutes after it starts.

For Wi-Fi, a streamer with no network opens a temporary Wi-Fi network of its own, about a minute after it starts. A streamer that was connected before waits about five minutes after losing its network. Use any phone or laptop:

  1. In its Wi-Fi settings, join Kalinka-Setup-XXXX. The four characters after the dash differ from streamer to streamer.
  2. Enter the password kalinka-setup: lowercase, with a hyphen. If your device warns that there is no internet, choose to stay connected.
  3. A setup page opens. If it does not, open http://192.168.4.1 in the browser.
  4. Choose your home Wi-Fi and enter its password.
  5. The streamer leaves the setup network and joins yours. Reconnect your phone or laptop to your home Wi-Fi, then open Kalinka. If the streamer could not join, the setup network comes back, so you can try again.

Keep these steps at hand: while your phone or laptop is on the setup network, it has no internet.

With the Kalinka app on a phone, you can set up the streamer over Bluetooth instead, and your phone stays on your home Wi-Fi. Start the app, choose to set up a streamer, and follow the steps.

Both ways need Wi-Fi in the streamer, and Bluetooth needs Bluetooth in it too. Every Pi listed above has both, except Compute Modules without wireless. On a PC, the Wi-Fi adapter must support access-point mode. The setup network uses 2.4 GHz.

Open Kalinka

With the Kalinka app. Install it on a phone or computer on the same network; the app's page says which file to download for Android, Windows or Linux. The app finds the server by itself. A new server is called My Kalinka Service.

With a web browser. Open http://kalinka.local:8000 for a streamer started from an image, or the host name you gave Raspberry Pi Imager in place of kalinka, as in http://livingroom.local:8000. A second one called kalinka on the same network becomes kalinka-2.local. Otherwise open http://<address>:8000, for example http://192.168.1.50:8000. Type the http:// and the :8000. To find the address:

  • the Kalinka app shows it under the server's name;
  • your router's list of connected devices shows the streamer as kalinka, or by the host name you gave Imager;
  • a screen plugged into a Raspberry Pi streamer shows it above the login prompt, unless it runs the now-playing display;
  • on a computer where you ran the install command, hostname -I prints it.

The first time, Kalinka walks you through setup. Follow the steps it shows. On a Raspberry Pi, choosing a DAC HAT there restarts the Pi once.

Put your music on it

Kalinka can read music from several places at once. Choose them during setup, and add more later in the app.

On a NAS or another computer. Nothing to copy. Add a Network share: the address of the NAS, the name of the share followed by any folder inside it (for example music/Albums), and the user name and password of an account on the NAS, or Guest for an open share.

  • The NAS must offer SMB2 or later. A very old NAS, or a router sharing a USB disk, may offer only SMB1: turn on SMB2 or SMB3 in its settings.
  • Kalinka looks for new and changed music on a share every 15 minutes. Set Scan interval to 0 in the My Library settings to have it look only when Kalinka starts and when you choose Rescan library.
  • Recycle bins, snapshots, thumbnail folders and hidden folders are skipped.

Copied onto the streamer. Every installation has a music folder, /srv/kalinka/music, that Kalinka reads from the start. Copy into it with a program that speaks SFTP. On an image you need a login first: the one you gave Raspberry Pi Imager, with SSH on, or one you create with SSH access on the control page.

On Use
Windows WinSCP: protocol SFTP, host = the streamer's address, your user name and password. Open /srv/kalinka/music and drag your albums in.
macOS Cyberduck: Open Connection → SFTP, the same details.
Linux In your file manager, open sftp://<user>@<address>/srv/kalinka/music.
Terminal scp -r ~/Music/* <user>@<address>:/srv/kalinka/music/

Albums appear once they have finished copying.

On a USB disk or stick plugged into the streamer. Just plug it in. Kalinka mounts it read-only, and within a few seconds Drives appears among your music sources: browse its folders and play straight from it, with its tags and cover art, without waiting for anything to be indexed. To keep a disk's music in My Library, open it or one of its folders and choose Add to library. FAT32, exFAT, NTFS, HFS+, ext4, XFS, Btrfs and F2FS are mounted; a disk you have put in /etc/fstab is left to you. On ext4, XFS, Btrfs and F2FS the server, which runs as the user kalusr, reads only the files that every user may read. Pulling the disk out without ejecting it is safe, as Kalinka never writes to it; Eject in the drive's menu also powers it down. With Mount USB drives automatically off, in Configuration → Streamer → Storage, a drive waits in Drives & shares to be mounted; once it is mounted, tick its Mount when plugged in and Kalinka mounts it at every start and whenever it is plugged in.

On an NFS share, or a second disk inside the streamer. Open Configuration → Streamer → Storage → Drives & shares. Disks inside the streamer that nothing has mounted are listed under On this streamer, and the shares of a NAS that announces itself on the network under Found on your network; reach any other with +, Add network share. Tap one and choose Mount: it mounts read-only and is kept with Mount after restart on, so Kalinka mounts it again at every start. Unmount leaves that as it is; a mounted one's dialog changes it. A share that will not mount says what to put right, with the mount's own words under Technical details. It appears under Drives like a USB disk. Mounting needs the helper the Kalinka package installs, so a server run from a source checkout lists drives and shares but cannot mount them. NFS needs the nfs-common package, which the installer adds when it can.

  • Kalinka reads a share as the user kalusr, and NFS lets a reader in by its user id. Make the files readable by everyone, or have the NAS map every client to one user (squashing, called Map all users on many NAS boxes).
  • A NAS that serves only NFSv4 often lists no shares. Type the export's path, such as /volume1/music, as the Folder in Add network share.

In another folder on the streamer. Add it as a Folder on this streamer. The server runs as the user kalusr and can only read files that every user may read. A folder in your home usually needs this once:

chmod o+X /home/<you>
chmod -R o+rX /home/<you>/Music

The library then fills in by itself: Kalinka finds your files, tidies their details online and, if you turned it on, prepares smart search. On a Raspberry Pi with a large collection the first pass can take hours. Kalinka works normally in the meantime.

Add more outputs

The server's own machine already has an output. You can add:

  • a Kalinka renderer on another machine, for the best sound: bit-perfect and gapless. Any 64-bit Linux machine near an amplifier or DAC will do: a Raspberry Pi from the Zero 2 W up, an old laptop or a mini-PC;
  • a browser tab, for quick listening with nothing to install. Open http://<address>:8000 and pick the browser as the output. It is not gapless or bit-perfect.

To set up a renderer on another machine:

  1. Give it 64-bit Debian 13, Raspberry Pi OS (64-bit, Trixie), Ubuntu 26.04 or Fedora 44. For a Pi, follow steps 1–4 of Starting from a blank Raspberry Pi under option D. Choose a host name that says where it is, such as livingroom: the output is named after it.

  2. On that machine, run:

    curl -fsSL https://kalinkaplayer.com/install-renderer.sh | sudo bash

    On a Pi with a DAC HAT, install the supervisor with it, so the app can set the HAT up:

    curl -fsSL https://kalinkaplayer.com/install-renderer.sh | sudo env KALINKA_SUPERVISOR=1 bash
  3. Within a few seconds the output appears in the app. Choose it, pick the sound device in its settings, and play a test sound.

Good to know:

  • The renderer must be on the same network as the server. Guest Wi-Fi, Wi-Fi with "client isolation" and separate VLANs block it.
  • Do not use a second Kalinka image as an output: an image always brings a server too, and a second server would appear in the app.
  • There is no renderer for Windows or macOS. Use a browser tab there.

The supervisor

The supervisor is a small service that looks after the streamer. It runs separately from Kalinka, so it keeps working when Kalinka has stopped or a plugin breaks it. It gives you:

  • the control page, at http://<address>:8001;
  • Wi-Fi setup over the temporary network or Bluetooth when the streamer is not connected;
  • from the app: restarting or switching off the streamer, setting its time zone, choosing a Raspberry Pi's DAC HAT, and restarting Kalinka when it stops answering.

The images include it. On a streamer you installed with a command, add it as below.

Add the supervisor to a streamer

This works on any streamer that runs Debian 13, Raspberry Pi OS (64-bit), DietPi or Ubuntu 26.04, with the server, a renderer, or both. You do not need to flash anything. On that streamer, run:

curl -fsSL https://raw.githubusercontent.com/Kalinka-Player/KalinkaPlayer/main/scripts/install-supervisor.sh | sudo bash

On the server's own machine you can do it from the app instead: turn on Manage this streamer in the advanced settings and apply. Kalinka restarts while the supervisor is installed; the computer itself does not.

Once installed, it is upgraded together with Kalinka. To remove it, turn Manage this streamer off again, or run sudo apt remove kalinka-supervisor.

  • Wi-Fi setup without a cable needs a Wi-Fi adapter in the streamer, and works on DietPi and on systems where NetworkManager runs the network, such as Raspberry Pi OS. Elsewhere, you still get the control page and everything else.
  • On a Pi running Raspberry Pi OS, turn I²C on (sudo raspi-config nonint do_i2c 0) so the supervisor can recognise a DAC HAT by its chip. Without it, you pick the HAT from the full list.
  • It is not available on Fedora.

The control page

Open http://<address>:8001 in a browser. It shows:

  • whether Kalinka is running, the installed versions, and how much memory and processor time Kalinka uses;
  • buttons to restart Kalinka, restart or power off the streamer, and reinstall Kalinka from kalinkaplayer.com. Reinstalling keeps your settings and music;
  • the installed plugins, each with a Remove button, so a plugin that stops Kalinka from starting can be taken away;
  • on a Raspberry Pi, the DAC HAT it found and the one it is set up for;
  • the time zone;
  • SSH access: enter a password of 12 characters or more to create the login kalinka-admin, with administrator rights. Connect with ssh kalinka-admin@<address> and use sudo for administrator commands. The page also checks OpenSSH's password authentication settings and reports a refusal or an incomplete check. Other SSH access rules still apply.

The page answers anyone on your home network, over plain HTTP, and nobody outside it. Anyone who can open it can set the administrator password, so use it on a network you trust. To turn it off, add KALINKA_CONTROL_API=0 to /etc/default/kalinka-supervisor and run sudo systemctl restart kalinka-supervisor. The supervisor's control page and API describes it in full.

Settings on the card

The Raspberry Pi images apply what Raspberry Pi Imager writes onto the card, at the first start:

  • the host name, which also names the streamer on your network as <name>.local;
  • your Wi-Fi network, hidden or not, with its country;
  • a login with administrator rights: your user name and password, your SSH public keys, or both. SSH is switched on if you asked for it. With public-key authentication only, that login takes no password over SSH. Call it kalinka-admin, and it is the login the control page's SSH access sets a password for, which removes that account's card-written password restriction. Other SSH policies still apply;
  • the time zone.

The keyboard layout is not used, as there is no keyboard to type on, and neither is Raspberry Pi Connect.

Then the files Imager wrote are overwritten and removed: they hold your Wi-Fi and login passwords, on a partition anyone with the card can read. A setting that cannot be used is left out and the rest still apply; with a login, journalctl -u kalinka-card-settings says what was left out and why. If the streamer cannot join the Wi-Fi you gave, it opens the setup network instead, two or three minutes after it starts.

A custom.toml you write onto the card yourself, in the format Raspberry Pi OS reads (config_version = 1, with [system], [user], [ssh], [wlan] and [locale] tables), is applied the same way at the next start. A login given only SSH keys can log in, but cannot use sudo, which asks for a password.

The files Raspberry Pi OS guides tell you to put on the card work too, so a card written with balenaEtcher, or with Imager but without its settings, can still have them. Once the card is written, take it out and put it back in, and save them onto the partition your computer opens:

  • userconf.txt: one line, your user name, a colon and your password's hash, which echo 'your password' | openssl passwd -6 -stdin prints. That gives a login with administrator rights, as above.
  • wpa_supplicant.conf: your Wi-Fi, as below, with your country's two-letter code in place of GB. Add scan_ssid=1 inside the braces for a hidden network. The password can also be its 64-digit key, without the quotes. Only the first network in the file is used.
  • an empty file called ssh or ssh.txt, which switches SSH on.
country=GB
network={
    ssid="Your network"
    psk="Your Wi-Fi password"
}

They are applied, overwritten and removed at the next start, as Imager's files are. A file that cannot be read is named in the journal and the others still apply. Where Imager's settings and these files give the same setting, Imager's is used.

Images from the kalinka-image-v4.2.0 release and older read none of these settings, and a card Imager customised may not finish their first start: write those without Imager's settings, or take a newer image.

Without any of these settings, and always on the PC image, which does not support them, the streamer starts with no login and no Wi-Fi, and everything is set up after the first start:

A streamer takes its network address from your router. On a network that gives out no addresses, such as a switch with no router, nothing can reach it.

Keeping it up to date

Kalinka checks for a new release every hour, and the app offers to install it. You can also let it update by itself: turn on automatic updates in the app, and it installs them between 3 and 6 in the morning, by the streamer's clock, while nothing is playing. Everything on the streamer updates together: the server, its plugins, the browser player, the supervisor and the renderer. Renderers on other machines go first, while they are connected to the server.

A renderer that falls behind shows an upgrade button in the app. To have one update itself every night, even when the server is off, run this on its machine:

sudo systemctl enable --now kalinka-renderer-upgrade.timer

Kalinka does not update the operating system. On an image, log in and run sudo apt update && sudo apt full-upgrade.

Kalinka used to install a C compiler and Python's development files for Smart Search as well, about 300 MB that nothing uses any more. An update leaves them in place, so unless you compile software on the streamer yourself, remove them with sudo apt-get remove build-essential python3-dev, then sudo apt-get autoremove for what they brought with them. That second command offers every package nothing needs any more, not only theirs, so read its list before you agree.

Troubleshooting

The app finds no server. The phone and the streamer must be on the same network. Guest Wi-Fi, Wi-Fi with "client isolation" and a VM on NAT all hide the server. Enter the address by hand in the app, as <address>:8000: if that works, only discovery is blocked.

The browser cannot connect. Wait a few minutes after switching the streamer on. Type http://, not https://, and :8000 at the end.

The Pi does not start. Check that you wrote the right image: rpi5 for a Pi 5, rpi234 for the others. Write the card again, try another card, and use the official power supply.

The setup Wi-Fi does not appear. The streamer only opens it when it has no network. If a cable is plugged in, unplug it, or open Kalinka over the cable instead. Give it a few minutes after switching on.

Wi-Fi is very slow, or the streamer drops off the network until it is unplugged. The Pi's Wi-Fi power saving does this. Update the streamer: recent supervisors turn it off for every network the streamer joins. The Network card of the control page shows whether it is on or off, and switches it.

No outputs in the list, or no sound. On the streamer, systemctl status kalinka-renderer should say active (running). If the unit is not found, no output is installed there: run the renderer command from Add more outputs. If there is no sound, pick another sound device in the output's settings: HDMI, the headphone socket and a USB DAC are separate devices. On a Pi, HDMI, the headphone socket and a HAT without an ID chip stay silent until you choose them as the sound card in the app. Until then, you can listen in the browser.

An output on another machine does not appear. On that machine, run sudo journalctl -u kalinka-renderer -f. A line with [Discovery] Found means it has seen the server. Without one, the network is blocking discovery: put both on the same network, or point the renderer at the server directly:

sudo systemctl edit kalinka-renderer

In the editor, add these lines with your server's address, save, and run sudo systemctl restart kalinka-renderer:

[Service]
ExecStart=
ExecStart=/usr/bin/kalinka-renderer --server 192.168.1.50:8000

The library stays empty. The folder is wrong, or the kalusr user cannot read it; see Put your music on it. For a network share, the share's status in the app says what the NAS answered: a wrong password, a share it does not have, or only SMB1.

Kalinka does not start. Open the control page: it shows what failed, can remove a broken plugin, and can reinstall Kalinka.

Logs. While the server runs, the app can download its logs as a ZIP. Passwords and keys are removed, but file names and network addresses remain, so look through it before posting it. When the server does not start, save the logs on the streamer:

sudo journalctl -u kalinka -u kalinka-upgrade -u kalinka-restart --since "1 day ago" > kalinka.log
sudo journalctl _TRANSPORT=kernel --since "1 day ago" > kernel.log

For a renderer, use -u kalinka-renderer -u kalinka-renderer-upgrade in the first command.

The second command saves the kernel's messages, among them its report when the streamer ran out of memory and stopped the server. It has to be a command of its own: given -u and another match, journalctl keeps only the records that fit both, and the kernel's records belong to no unit. It does not use -k, which reads only since the streamer last started and would miss a crash that restarted it.

Asking for help. Questions are welcome in the testing thread. Something you can reproduce is easier to act on as an issue.