Getting started on Aether

Installation

Mon, 01 Jan 0001 00:00:00 +0000

Installation#

Every release ships:

Download	For
`aether_<version>_linux_amd64_v1.deb`, `…_amd64_v3.deb`, `…_linux_arm64.deb`	Debian, Ubuntu and derivatives
`ghcr.io/andresbott/aether`	Docker / Podman, amd64 and arm64
`aether_Linux_.zip`, `aether_Windows_.zip`, `aether_Darwin_*.zip`	the plain binary, any other system
`aether-spa.zip`	the web UI on its own (rarely needed, see below)

v1 or v3? The amd64 builds come in two flavours. v3 is a little faster and needs a CPU from 2013 (Intel Haswell) or 2017 (AMD Zen) onwards; v1 runs on any 64-bit x86 CPU. A v3 build on an older CPU exits immediately with an “illegal instruction” error — pick v1 when unsure.

Configuration

Mon, 01 Jan 0001 00:00:00 +0000

Configuration#

Aether reads one YAML file. Every option is annotated in the packaged config; this page covers the ones you will touch.

Where the config comes from#

aether start -c /path/to/config.yaml uses that file. The path must exist — a typo is an error, not a silent fallback.
Without -c, Aether tries ./config.yaml, then /etc/aether/config.yaml, and uses the first one that exists. With neither, built-in defaults apply.
Environment variables override the file: AETHER_ plus the key path in capitals, e.g. AETHER_SERVER_PORT=8080 or AETHER_AUTH_METHOD=native. Lists such as ScanFolders can only be set in the file.
Secrets can live in their own file: a value starting with @ is read from that path, e.g. FanartApiKey: "@/etc/aether/fanart.api.key".

Restart the server after changing the config.

Pre-release status

Mon, 01 Jan 0001 00:00:00 +0000

Pre-release status#

Aether has no stable release yet. Until it does, any new version may change the configuration file or the database, with no migration from what an older version left behind:

Configuration. Options can be renamed, moved or removed. After an upgrade, compare your config with the packaged config of the new version.
Database. A new version may not work with an older version’s database. The way out is an empty data directory and a fresh scan.

Your files are the source of truth#

Aether is built so that losing its database costs you a rescan, not your collection. What it knows about your music comes from the files — tags, embedded and folder covers — and the metadata editor writes its changes back into them. A scan reads all of it again.