From 0bc8dabb54f6b5e7d3cdbdc2684fadd948fb6291 Mon Sep 17 00:00:00 2001
From: Joey Hess <joey@kitenet.net>
Date: Fri, 28 Feb 2014 22:39:06 -0400
Subject: [PATCH] docs for remote webapp, securely

---
 doc/git-annex.mdwn                | 17 ++++++++++----
 doc/tips/remote_webapp_setup.mdwn | 38 +++++++++++++++++++++++++++++++
 2 files changed, 50 insertions(+), 5 deletions(-)
 create mode 100644 doc/tips/remote_webapp_setup.mdwn

diff --git a/doc/git-annex.mdwn b/doc/git-annex.mdwn
index 9b9b53902f..40e6adb2ab 100644
--- a/doc/git-annex.mdwn
+++ b/doc/git-annex.mdwn
@@ -307,11 +307,18 @@ subdirectories).
   By default, the webapp can only be accessed from localhost, and running
   it opens a browser window.
 
-  With the `--listen=address[:port]` option, the webapp can be made to listen
-  for connections on the specified address. This disables running a
-  local web browser, and outputs the url you can use to open the webapp
-  from a remote computer.
-  Note that this does not yet use HTTPS for security, so use with caution!
+  To use the webapp on a remote computer, use the `--listen=address`
+  option to specify the address the web server should listen on.
+  This disables running a local web browser, and outputs the url you
+  can use to open the webapp.
+
+  When using the webapp on a remote computer, you'll almost certianly
+  want to enable HTTPS. The webapp will use HTTPS if it finds
+  a .git/annex/privkey.pem and .git/annex/certificate.pem. Here's
+  one way to generate those files, using a self-signed certificate:
+
+    openssl genrsa -out .git/annex/privkey.pem 4096
+    openssl req -new -x509 -key .git/annex/privkey.pem > .git/annex/certificate.pem
 
 # REPOSITORY SETUP COMMANDS
 
diff --git a/doc/tips/remote_webapp_setup.mdwn b/doc/tips/remote_webapp_setup.mdwn
new file mode 100644
index 0000000000..599841a34e
--- /dev/null
+++ b/doc/tips/remote_webapp_setup.mdwn
@@ -0,0 +1,38 @@
+Here's the scenario: You have a remote server you can ssh into,
+and you want to use the git-annex webapp there, displaying back on your local
+web browser.
+
+Sure, no problem! It can even be done securely!
+
+First, you need to generate a private key and a certificate for HTTPS.
+These files are stored in `.git/annex/privkey.pem` and 
+`.git/annex/certificate.pem` inside the git repository. Here's
+one way to generate those files, using a self-signed certificate:
+
+	openssl genrsa -out .git/annex/privkey.pem 4096
+	chmod 400 .git/annex/privkey.pem
+	openssl req -new -x509 -key .git/annex/privkey.pem > .git/annex/certificate.pem
+
+With those files in place, git-annex will automatically only accept HTTPS
+connections. That's good, since HTTP connections are not secure over the
+big bad internet.
+
+All that remains is to start the webapp listening on the external interface
+of the server. Normally, for security, git-annex only listens on localhost.
+
+	git annex webapp --listen=host.example.com
+
+(If your hostname doesn't work, its IP address certianly will..)
+
+When you run the webapp like that, it'll print out the URL to use to open
+it. You can paste that into your web browser.
+
+Notice that the URL has a big jumble of letters at the end -- this is a secret
+token that the webapp uses to verify you're you. So random attackers can't find
+your webapp and do bad things with it.
+
+The webapp also writes its url to `.git/annex/url`, so you can use that
+file to automate opening the url. For example, you could make your server
+start the webapp on boot, and then to open it, run:
+
+	xdg-open "$(ssh host.example.com cat annex/.git/annex/url)"