From ccbdaf044832e3f4376bba3c78305f578c392d88 Mon Sep 17 00:00:00 2001 From: Joey Hess Date: Sun, 28 Jul 2024 17:19:27 -0400 Subject: [PATCH] documentation for p2phttp --- CHANGELOG | 2 ++ doc/tips/clusters.mdwn | 3 ++ ...tup_a_public_repository_on_a_web_site.mdwn | 12 ++++++- doc/tips/smart_http_server.mdwn | 36 +++++++++++++++++++ doc/todo/git-annex_proxies.mdwn | 4 +++ 5 files changed, 56 insertions(+), 1 deletion(-) create mode 100644 doc/tips/smart_http_server.mdwn diff --git a/CHANGELOG b/CHANGELOG index b99c536bd8..db33d0ba37 100644 --- a/CHANGELOG +++ b/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. diff --git a/doc/tips/clusters.mdwn b/doc/tips/clusters.mdwn index fe79bb3875..eed3717cdb 100644 --- a/doc/tips/clusters.mdwn +++ b/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 diff --git a/doc/tips/setup_a_public_repository_on_a_web_site.mdwn b/doc/tips/setup_a_public_repository_on_a_web_site.mdwn index e8cfd8f978..2c21e61267 100644 --- a/doc/tips/setup_a_public_repository_on_a_web_site.mdwn +++ b/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]]. diff --git a/doc/tips/smart_http_server.mdwn b/doc/tips/smart_http_server.mdwn new file mode 100644 index 0000000000..f2440036b9 --- /dev/null +++ b/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. diff --git a/doc/todo/git-annex_proxies.mdwn b/doc/todo/git-annex_proxies.mdwn index f94c65490a..fcec9843fe 100644 --- a/doc/todo/git-annex_proxies.mdwn +++ b/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 -- 2.30.2