Document custom upgrade server

dev/release-signing.rst

@@ -1,3 +1,5 @@
+.. _release-signing:
+
 Release Signing
 ===============
 

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`.