From 230f3f61768561ba9fa2709ac2af6475bf561308 Mon Sep 17 00:00:00 2001
From: Antoine Martin <antoine@alarsyo.net>
Date: Tue, 30 Mar 2021 00:55:07 +0200
Subject: [PATCH] README: write setup documentation

---
 README.org | 62 ++++++++++++++++++++++++++++++++++++++++++++++++++++++
 1 file changed, 62 insertions(+)

diff --git a/README.org b/README.org
index e56966a..cbe07d6 100644
--- a/README.org
+++ b/README.org
@@ -21,6 +21,68 @@ file at the repo root.
 This is a very destructive process: anything removed from the single source of
 truth is effectively removed from any mirror as well.
 
+** Setup
+
+*** Quickstart
+
+Setting up =lohr= should be quite simple:
+
+1. Create a =Rocket.toml= file and [[https://rocket.rs/v0.4/guide/configuration/][add your configuration]].
+
+2. Run =lohr=:
+
+   #+begin_src sh
+   $ cargo run # or `cargo run --release` for production usage
+   #+end_src
+
+3. Configure your favorite git server to send a webhook to =lohr='s address on
+   every push event.
+
+   I used [[https://docs.gitea.io/en-us/webhooks/][Gitea's webhooks format]], but I *think* they're similar to GitHub and
+   GitLab's webhooks, so these should work too! (If they don't, *please* file an
+   issue!)
+
+4. Add a =.lohr= file containing the remotes you want to mirror this repo to:
+
+   #+begin_example
+   git@github.com:you/your_repo
+   #+end_example
+
+   and push it. That's it! =lohr= is mirroring your repo now.
+
+*** Configuration
+
+**** Home directory
+
+=lohr= needs a place to clone repos and store its data. By default, it's the
+current directory, but you can set the =LOHR_HOME= environment variable to
+customize it.
+
+**** Extra remote configuration
+
+=lohr= looks for a =lohr-config.yaml= file in its =LOHR_HOME= directory. This
+file takes the following format:
+
+#+begin_src yaml
+default_remotes:
+  - "git@github:user"
+  - "git@gitlab:user"
+
+additional_remotes:
+  - "git@git.sr.ht:~user"
+#+end_src
+
+- ~default_remotes~ is a list of remotes to use if no ~.lohr~ file is found in a
+  repository.
+- ~additional_remotes~ is a list of remotes to add in any case, whether the
+  original set of remotes is set via ~default_remotes~ or via a =.lohr= file.
+
+Both settings take as input a list of "stems", i.e. incomplete remote addresses,
+to which the repo's name will be appended (so for example, if my
+~default_remotes~ contains ~git@github.com:alarsyo~, and a push event webhook
+is received for repository =git@gitlab.com:some/long/path/repo_name=, then the
+mirror destination will be =git@github.com:alarsyo/repo_name=.
+
 ** Contributing
 
 I accept patches anywhere! Feel free to [[https://github.com/alarsyo/lohr/pulls][open a GitHub Pull Request]], [[https://gitlab.com/alarsyo/lohr/-/merge_requests][a GitLab