Doc updates

README.md

@@ -19,7 +19,7 @@ Password: `demo_password`
 - Optimized for large music collections
 - Can run on Windows, Linux, BSD, or through Docker
 - Support for `flac`, `mp3`, `mp4`, `mpc`, `ogg`, `opus`, `ape`, `wav` and `aiff` files
-- Easy to setup and administer, no configuration files needed
+- Easy to setup and administer, no configuration files required
 - Dark mode and customizable color themes
 - Listen to your music on the go:
   - Polaris Android ([Google Play Store](https://play.google.com/store/apps/details?id=agersant.polaris) · [F-Droid](https://f-droid.org/packages/agersant.polaris/) · [Repository](https://github.com/agersant/polaris-android))
@@ -33,6 +33,7 @@ Password: `demo_password`
 
 ## Documentation
 
+- [Configuration](docs/CONFIGURATION.md)
 - [Contribute to Polaris](docs/CONTRIBUTING.md)
 - [Maintenance Runbooks](docs/MAINTENANCE.md)
 

docs/CONFIGURATION.md

@@ -0,0 +1,50 @@
+# Configuration
+
+Polaris configuration resides in a single text file whose format is documented below. You can use the Polaris web UI to modify the configuration, or write to it in any text editor. You may edit the configuration file while Polaris is running.
+
+## Location
+
+The location of the configuration file is always logged during Polaris startup. It is determined as follows:
+
+- From the `--config` (or `-c`) CLI option if present. This option must point to the `.toml` file.
+- If the CLI option is not specified, Polaris will look for a `polaris.toml` file, inside the directory specified by the `POLARIS_CONFIG_DIR` environment variable _at compilation time_. When using the Windows installer, this will be `%LOCALAPPDATA%/Permafrost/Polaris/polaris.toml`. When using the supplied Makefile, the default is either `/usr/local/etc/polaris` (for a system-wide installations), or `~/.config/polaris` (for a XDG installation).
+- If `POLARIS_CONFIG_DIR` was not set when Polaris was compiled, it will default to `.` on Linux, and the `LOCALAPPDATA` location mentioned above on Windows. This behavior on Windows may change in future releases.
+
+## Format
+
+The configuration file uses the [TOML](https://toml.io/) format. Everything in the configuration file is optional and may be ommitted (unless mentioned otherwise).
+
+```toml
+# Regular expression used to identify album art in files adjacent to an audio file
+album_art_pattern = "Folder.(jpeg|jpg|png)"
+# A URL Polaris will regularly make requests to in order to update Dynamic DNS
+ddns_url = "https://example.com?token=foobar"
+
+# Array of locations Polaris should scan to find music files
+[[mount_dirs]]
+# Directory to scan
+source = "/home/example/music"
+# User-facing name for this directory (must be unique)
+name = "My Music 🎧️"
+
+[[mount_dirs]]
+source = "/mnt/example/more_music"
+name = "Extra Music 🎵"
+
+# Array of user accounts who can connect to the Polaris server
+[[users]]
+# Username for login
+name = "example-user"
+# If true, user will have access to all settings in the web UI
+admin = true
+# Plain text password for this user. Will be ignored if hashed_password is set. Polaris will never write to this field. For each user, at least one of initial_password and hashed_password must be set.
+initial_password = "top-secret-password"
+# Hashed and salted password for the user. Polaris will create this field if unset.
+hashed_password = "$pbkdf2-sha256$i=10000,l=32$SI8LjK1KtvcawhgmWGJgRA$t9btMwhUTQ8r3vqI1xhArn19J7Jezyoi461fFjhZXGU"
+
+[[users]]
+name = "other-user"
+admin = true
+initial_password = "amospheric-strawberry64"
+```
+

docs/CONTRIBUTING.md

@@ -10,13 +10,13 @@ Compiling and running Polaris is very easy as it only depends on the Rust toolch
 
 Polaris supports a few command line arguments which are useful during development:
 
+- `-c some/config.toml` sets the location of the configuration file. This is useful to preconfigure users and music directories.
+- `--data some/path` sets the folder Polaris will use to store runtime data such as playlists, collection index and auth secrets.
 - `-w some/path/to/web/dir` lets you point to the directory to be served as the web interface. You can find a suitable directory in your Polaris install (under `/web`), or from the [latest polaris-web release](https://github.com/agersant/polaris-web/releases/latest/download/web.zip).
 - `-s some/path/to/swagger/dir` lets you point to the directory to be served as the swagger API documentation. You'll probably want to point this to the `/docs/swagger` directory of the polaris repository.
-- `-d some/path/to/a/file.db` lets you manually choose where Polaris stores its configuration and music index (you can reuse the same database accross multiple runs).
-- `-c some/config.toml` lets you use a configuration file to add content to the database. This can be useful if you frequently delete the database and would like to automate the first time flow. The configuration format is not documented but can be inferred by looking at the `Config` struct in `config.rs`.
 - `-f` (on Linux) makes Polaris not fork into a separate process.
 
-Putting it all together, a typical command to compile and run the program would be: `cargo run -- -w web -s docs/swagger -d test-output/my.db`
+Putting it all together, a typical command to compile and run the program would be: `cargo run -- -w web -s docs/swagger -c test-config.toml`
 
 While Polaris is running, access the web UI at [http://localhost:5050](http://localhost:5050).
 

src/app/config.rs

@@ -22,7 +22,7 @@ use super::auth;
 pub struct Config {
 	pub reindex_every_n_seconds: Option<u64>,
 	pub album_art_pattern: Option<Regex>,
-	pub ddns_url: Option<http::Uri>,
+	pub ddns_update_url: Option<http::Uri>,
 	pub mount_dirs: Vec<MountDir>,
 	pub users: Vec<User>,
 }
@@ -43,7 +43,7 @@ impl TryFrom<storage::Config> for Config {
 			None => None,
 		};
 
-		config.ddns_url = match c.ddns_url.map(http::Uri::try_from) {
+		config.ddns_update_url = match c.ddns_update_url.map(http::Uri::try_from) {
 			Some(Ok(u)) => Some(u),
 			Some(Err(_)) => return Err(Error::DDNSUpdateURLInvalid),
 			None => None,
@@ -59,7 +59,7 @@ impl From<Config> for storage::Config {
 			reindex_every_n_seconds: c.reindex_every_n_seconds,
 			album_art_pattern: c.album_art_pattern.map(|p| p.as_str().to_owned()),
 			mount_dirs: c.mount_dirs.into_iter().map(|d| d.into()).collect(),
-			ddns_url: c.ddns_url.map(|u| u.to_string()),
+			ddns_update_url: c.ddns_update_url.map(|u| u.to_string()),
 			users: c.users.into_iter().map(|u| u.into()).collect(),
 		}
 	}
@@ -157,12 +157,12 @@ impl Manager {
 	}
 
 	pub async fn get_ddns_update_url(&self) -> Option<http::Uri> {
-		self.config.read().await.ddns_url.clone()
+		self.config.read().await.ddns_update_url.clone()
 	}
 
 	pub async fn set_ddns_update_url(&self, url: Option<http::Uri>) -> Result<(), Error> {
 		self.mutate(|c| {
-			c.ddns_url = url;
+			c.ddns_update_url = url;
 		})
 		.await
 	}

src/app/config/storage.rs

@@ -28,7 +28,7 @@ pub struct Config {
 	#[serde(default, skip_serializing_if = "Vec::is_empty")]
 	pub mount_dirs: Vec<MountDir>,
 	#[serde(skip_serializing_if = "Option::is_none")]
-	pub ddns_url: Option<String>,
+	pub ddns_update_url: Option<String>,
 	#[serde(default, skip_serializing_if = "Vec::is_empty")]
 	pub users: Vec<User>,
 }