📝 document how to run `ptth_server`

This commit also works well on Termux on Android.

crates/ptth_server/src/bin/ptth_server.rs

@@ -2,7 +2,6 @@
 
 use std::{
 	fs::File,
-	io::Write,
 	path::{Path, PathBuf},
 };
 
@@ -10,6 +9,7 @@ use structopt::StructOpt;
 
 use ptth_server::{
 	load_toml,
+	prelude::*,
 	run_server,
 };
 
@@ -51,8 +51,7 @@ pub struct ConfigFile {
 fn gen_and_save_key (path: &Path) -> anyhow::Result <()> {
 	let api_key = ptth_core::gen_key ();
 	
-	{
-		let mut f = File::create (path)?;
+	let mut f = File::create (path).with_context (|| format! ("Can't create config file `{:?}`", path))?;
 	
 	#[cfg (unix)]
 	{
@@ -65,11 +64,10 @@ fn gen_and_save_key (path: &Path) -> anyhow::Result <()> {
 	}
 	#[cfg (not (unix))]
 	{
-			tracing::warn! ("API keys aren't protected from clients on non-Unix OSes yet");
+		tracing::warn! ("Error VR6VW5QT: API keys aren't protected from clients on non-Unix OSes yet");
 	}
 	
 	f.write_all (format! ("api_key = \"{}\"\n", api_key).as_bytes ())?;
-	}
 	
 	Ok (())
 }
@@ -90,16 +88,16 @@ async fn main () -> Result <(), anyhow::Error> {
 			load_toml::load (&path)?
 		}
 		else {
-			panic! ("API key not provided in config file and auto-gen-key not provided");
+			bail! ("API key not provided in config file and auto-gen-key not provided");
 		},
 		Ok (x) => x,
 		Err (e) => return Err (e.into ()),
 	};
 	
 	let config_file = ptth_server::ConfigFile {
-		name: opt.name.or (config_file.name).expect ("`name` must be provided in command line or config file"),
+		name: opt.name.or (config_file.name).ok_or (anyhow::anyhow! ("`name` must be provided in command line or config file"))?,
 		api_key: config_file.api_key,
-		relay_url: opt.relay_url.or (config_file.relay_url).expect ("`relay_url` must be provided in command line or config file"),
+		relay_url: opt.relay_url.or (config_file.relay_url).ok_or (anyhow::anyhow! ("`--relay-url` must be provided in command line or `relay_url` in config file"))?,
 		file_server_root: opt.file_server_root.or (config_file.file_server_root),
 		throttle_upload: opt.throttle_upload,
 	};

crates/ptth_server/src/lib.rs

@@ -70,6 +70,8 @@ pub mod file_server;
 /// and checking permissions (On Unix)
 pub mod load_toml;
 
+pub mod prelude;
+
 use errors::ServerError;
 
 pub struct State {

crates/ptth_server/src/prelude.rs

@@ -0,0 +1,8 @@
+pub use std::{
+	io::Write,
+};
+
+pub use anyhow::{
+	Context,
+	bail,
+};

docs/how-to/run-ptth-server.md

@@ -0,0 +1,53 @@
+# How-to: Run `ptth_server`
+
+Note: On Termux for Android you might run `umask 0022` first. Otherwise
+`ptth_server` might accidentally make files world-unreadable when it opens
+them, and PTTH refuses to serve world-unreadable files. 0022 is the default
+on desktops, so this is probably an Android security thing. PTTH uses the
+same permissions to protect its config file, so the two interfere.
+
+## Without writing your own config file
+
+(Ideal if you're running `ptth_server` autonomously from a script or something)
+
+```
+ptth_server \
+--auto-gen-key \
+--config-path ptth_server.toml \
+--relay_url https://example.com/7ZSFUKGV \
+--name my_server_name
+```
+
+ptth_server will:
+
+- Try to use the API key from `ptth_server.toml`
+- If that config file doesn't exist, create it, mark it as not readable to other
+Unix users, and fill it with a random key
+- Attempt to contact the `ptth_relay` instance with the base URL `https://example.com/7ZSFUKGV`
+- Identify itself to that relay with the name `my_server_name` and the
+random key
+
+## With your own config file
+
+(Ideal for long-lived instances)
+
+```
+mkdir config
+touch config/ptth_server.toml
+chmod 600 config/ptth_server.toml
+dd if=/dev/urandom bs=64 count=1 | base64 >> config/ptth_server.toml
+```
+
+Open `config/ptth_server.toml` in your text editor.
+
+There will be 64 bytes of random Base64 in the file already. Use that for the
+`api_key` field. Fill out the other fields as desired:
+
+```
+name = "my_server_name"
+relay_url = "https://example.com/7ZSFUKGV"
+file_server_root = "/home/user/public"
+api_key = 
+```
+
+Then run `ptth_server` with no arguments.