From 015746163f925e5633a2b062ad42603e3e493172 Mon Sep 17 00:00:00 2001
From: Jakob Borg <jakob@nym.se>
Date: Thu, 10 Sep 2015 14:28:19 +0200
Subject: [PATCH] Document custom upgrade server

---
 dev/release-signing.rst   |  2 ++
 users/custom-upgrades.rst | 74 +++++++++++++++++++++++++++++++++++++++
 2 files changed, 76 insertions(+)
 create mode 100644 users/custom-upgrades.rst

diff --git a/dev/release-signing.rst b/dev/release-signing.rst
index ed665c508..aeb461bb4 100644
--- a/dev/release-signing.rst
+++ b/dev/release-signing.rst
@@ -1,3 +1,5 @@
+.. _release-signing:
+
 Release Signing
 ===============
 
diff --git a/users/custom-upgrades.rst b/users/custom-upgrades.rst
new file mode 100644
index 000000000..cdc66df05
--- /dev/null
+++ b/users/custom-upgrades.rst
@@ -0,0 +1,74 @@
+Custom Upgrade Server
+=====================
+
+Description
+-----------
+
+Syncthing by default upgrades automatically from the official release packages
+on Github. If this is unsuitable, Syncthing can instead be configured to look
+for upgrades on a local or private upgrade server.
+
+.. versionadded:: 0.12.0
+
+Usage
+-----
+
+The URL used to fetch release information can be set in :ref:`advanced`, under
+the name ``releasesURL``. The URL should point to a location serving a valid
+relase list. The release list is a JSON file on the following format::
+
+	[
+	  {
+	    "tag_name": "v0.11.24",
+	    "prerelease": false,
+	    "assets": [
+	      {
+	        "url": "https://api.github.com/repos/syncthing/syncthing/releases/assets/844913",
+	        "name": "syncthing-dragonfly-amd64-v0.11.24.tar.gz",
+	      },
+	      {
+	        "url": "https://api.github.com/repos/syncthing/syncthing/releases/assets/844914",
+	        "name": "syncthing-freebsd-386-v0.11.24.tar.gz",
+	      },
+	      {
+	        "url": "https://api.github.com/repos/syncthing/syncthing/releases/assets/844915",
+	        "name": "syncthing-freebsd-amd64-v0.11.24.tar.gz",
+	      },
+	      {
+	        "url": "https://api.github.com/repos/syncthing/syncthing/releases/assets/844916",
+	        "name": "syncthing-linux-386-v0.11.24.tar.gz",
+	      },
+	      ...
+	    ]
+	  },
+	  {
+	    "tag_name": "v0.11.23",
+	    "prerelease": false,
+	    "assets": [
+	      {
+	        "url": "https://api.github.com/repos/syncthing/syncthing/releases/assets/824903",
+	        "name": "syncthing-dragonfly-amd64-v0.11.23.tar.gz",
+	      },
+	      {
+	        "url": "https://api.github.com/repos/syncthing/syncthing/releases/assets/824904",
+	        "name": "syncthing-freebsd-386-v0.11.23.tar.gz",
+	      },
+	      {
+	        "url": "https://api.github.com/repos/syncthing/syncthing/releases/assets/824905",
+	        "name": "syncthing-freebsd-amd64-v0.11.23.tar.gz",
+	      },
+	      {
+	        "url": "https://api.github.com/repos/syncthing/syncthing/releases/assets/824906",
+	        "name": "syncthing-linux-386-v0.11.23.tar.gz",
+	      },
+	      ...
+	    ]
+	  }
+	  ...
+	]
+
+The file may include additional attributes; these are ignored. Syncthing looks
+for a version number in ``tag_name``, then for an asset ``name`` matching
+``syncthing-$os-$arch-$version.$ext``. The actual assets must be official
+releases downloaded from Github, or they must be custom compiled and signed
+according to the process outlined in :ref:`release-signing`.