Configuration

Tunetorch is configured in two places. They complement each other rather than overlap:

As a rule of thumb: whatever the container needs to know while starting up is an environment variable. Everything else you set in the interface.

Environment variables

They all start with TT_. If you run Tunetorch behind a TLS reverse proxy, you don't have to set a single one of them.

Paths

Network & security

Set TT_TRUSTED_PROXIES correctly. A value that's too high (or 1 without a real proxy) lets clients fake their IP address. That defeats the brute-force protection.

Operation

Schedules for maintenance tasks aren't set here. Which tasks run when is set in the interface (see Server administration).

Server settings

You'll find them under Server settings in the admin interface, sorted into sections. Changes take effect without a restart.

A section is saved as a whole: if the server rejects one value, the others stay unchanged too, and the message names the field that caused it. There are no half-saved sections. The same applies to resetting to the defaults.

Resetting to defaults

Every section has a ↺ button at the top. As long as all values are at their defaults, it barely stands out. If one differs, it turns the accent colour, even when the section is collapsed. Before saving, it shows you what will change (current → default).

Because the default comes straight from the server, an existing installation also picks up, with one click, a default value that changed in an update.

The same button also exists in every account's user settings.

Your server's name

Out of the box, your installation is called “Tunetorch” everywhere. With an active Pro subscription you give it a name of your own under Server settings → Tunetorch Pro → Name of this server, for example “Smith Family Music”. If the field stays empty, it's called “Tunetorch”.

Without an active subscription the field is missing. You don't lose anything that way: without Pro the server is called “Tunetorch” again anyway. Your name stays saved and is back immediately with the subscription.

Where the name appears:

The name is on the sign-in page, so it shows before anyone signs in. Anyone who knows your server's address sees it without signing in. That's intentional: the name is meant to greet you. If you don't want that, leave the field empty and it keeps saying “Tunetorch”. Your music and your data aren't affected; it's only about this one piece of text.

A web app that's already installed keeps its old name. The name under the icon on the home screen is fixed at installation. Browsers pick up later changes only with a delay or not at all. To see the new name there, remove the app and install it again.

The Android app stays “Tunetorch”, and that won't change. It can manage several servers. With three servers added, there'd be no right answer as to which name should be on the home screen. Inside the app you see your server name in the header as usual.

If your subscription expires, the server is called “Tunetorch” again. Your name stays saved and is back as soon as Pro returns.

Time zone

Out of the box the server runs in Europe/Berlin. You don't set the time zone with a Docker variable but in the interface (Server settings → Time zone), where you pick it from the complete IANA list.

It applies to the timestamps in the log, all dates and the fixed times of the maintenance tasks. A change takes effect immediately.

Reverse proxy & HTTPS

For access from the internet and for the installable PWA you need a reverse proxy with a TLS certificate. It forwards to port 5000 of the container.

Caddy (obtains the certificate itself):

music.example.com {
    reverse_proxy 127.0.0.1:5000
}

Nginx:

server {
    server_name music.example.com;
    listen 443 ssl;

    location / {
        proxy_pass         http://127.0.0.1:5000;
        proxy_set_header   Host              $host;
        proxy_set_header   X-Forwarded-For   $proxy_add_x_forwarded_for;
        proxy_set_header   X-Forwarded-Proto $scheme;
        proxy_read_timeout 300s;
    }
}

The X-Forwarded-For header is the important one. Tunetorch reads the caller's real IP from it for the brute-force protection. You specify how many proxies sit in front with TT_TRUSTED_PROXIES (default 1).

For large uploads under Nginx you also need a suitable client_max_body_size.

Layout of the data directory

/app/data/
├── db/                   the SQLite database (WAL)
├── backups/              backup copies of the database (automatic before schema updates)
├── audio/                uploaded original files + metadata backup (.txt)
├── audio_cache/          converted versions (limited automatically)
├── cover/                cover art in four sizes
├── interpret_hero/       artist images
├── person_hero/          photos of people
├── logs/                 server logs (rotating)
├── jwt/                  signing keys for sign-in
├── lizenz/               state of the Pro licence
├── redis/                persistent security data (blocks, token blocklist)
├── upload_temp/          running upload sessions
└── temp/                 exports and short-lived intermediate files

For a backup, this one directory is enough; see Security & backup.

Next step

• Adding music
• Server administration