documentation for p2phttp

CHANGELOG

@@ -3,6 +3,8 @@ git-annex (10.20240702) UNRELEASED; urgency=medium
   * New HTTP API that is equivilant to the P2P protocol.
   * annex+http and annex+https urls can be configured for
     remote.name.annexUrl to use the HTTP API to communicate with a server.
+    This supports writable repositories, as well as accessing clusters
+    and proxied remotes over HTTP.
   * New p2phttp command to serve the HTTP API.
   * Added a build flag for servant, enabling annex+http urls and 
     git-annex p2phttp.

doc/tips/clusters.mdwn

@@ -121,6 +121,9 @@ in the git-annex branch. That tells other repositories about the cluster.
 	Started proxying for node2
 	Started proxying for node3
 
+The cluster will now be accessible over ssh. To also let the cluster be
+accessed over http, you would need to set up a [[tips/smart_http_server]].
+
 Operations that affect multiple nodes of a cluster can often be sped up by
 configuring annex.jobs in the gateway repository.
 In the example above, the nodes are all disk bound, so operating

doc/tips/setup_a_public_repository_on_a_web_site.mdwn

@@ -28,4 +28,14 @@ Here's how I set it up. --[[Joey]]
 
 When users clone over http, and run git-annex, it will
 automatically learn all about your repository and be able to download files
-right out of it, also using http. 
+right out of it, also using http.
+
+----
+
+The above is a simple way to set that up, but it's not necessarily the
+*best* way. Both git and git-annex will be accessing the repository using
+dumb http, which can be innefficient. And it doesn't allow write access.
+
+For something smarter, you may want to also set up
+[git smart http](https://git-scm.com/book/en/v2/Git-on-the-Server-Smart-HTTP),
+and the git-annex equivilant, a [[smart_http_server]].

doc/tips/smart_http_server.mdwn

@@ -0,0 +1,36 @@
+git-annex can access a remote using any web server,
+as shown in the tip [[setup_a_public_repository_on_a_web_site]].
+
+That's limited to basic read-only repository access though. Git
+has [smart HTTP](https://git-scm.com/book/en/v2/Git-on-the-Server-Smart-HTTP)
+that can be used to allow pushes over http. And git-annex has an
+equivilant, the [[git annex-p2phttp command|/git-annex-p2phttp]].
+
+As well as allowing write access to authorized users over http,
+`git-annex p2phttp` also allows accessing [[clusters]], and other proxied
+remotes over http.
+
+You will still need to run a web server to serve the git repository.
+`git-annex p2phttp` only serves git-annex's own
+[[API|design/p2p_protocol_over_http]], and it does it
+on a different port (9417 by default).
+
+All you need to do on the server is to arrange to run 
+`git-annex p2phttp` in your repository as a daemon, or service.
+Note that it should not be run as root, but as whatever user owns the
+repository. It has several options you can use to configure it, including
+controlling who can access the repository.
+
+After cloning a repository, it's necessary to configure
+`remote.name.annexUrl` to an "annex+http" or "annex+https" url,
+so that git-annex knows where the API endpoint is.
+
+For example:
+
+    git clone http://example.com/foo.git
+    cd foo
+    git config remote.origin.annexUrl annex+http://example.com/git-annex/bbdac17e-6633-4b27-8f7b-fb447d5bae7c
+    git-annex get ...
+
+The last part of the "annex+http" url is the annex.uuid of the
+remote repository.

doc/todo/git-annex_proxies.mdwn

@@ -56,6 +56,10 @@ Planned schedule of work:
 
 ## items deferred until later for p2p protocol over http
 
+* `git-annex p2phttp` should support serving several repositories at the same
+  time (not as proxied remotes), so that eg, every git-annex repository
+  on a server can be served on the same port.
+
 * Support proxying to git remotes that use annex+http urls.
 
 * `git-annex p2phttp` could support systemd socket activation. This would