git-annex/doc/tips/smart_http_server.mdwn

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

You will need 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.

So there are two web servers, and thus two different urls.
A remote will have `remote.name.url` set to the http url
that git will use, and also have `remote.name.annexUrl` set to the url
that git-annex will use to talk to `git-annex p2phttp`. That url
looks like this:
    
    annex+http://example.com/git-annex/

The "annex+http" (or "annex+https") indicates that it's a git-annex API
url, which defaults to being on port 9417 unless a different port is set.

It would be annoying if every user who cloned your repository 
had to set `remote.name.annexUrl` manually. So there's a way to automate it.
In the git config file of the repository, set `annex.url` to the "annex+http"
(or "annex+https") url. The first time it uses a http remote, git-annex
downloads its git config file, and sets `remote.name.annexUrl` to the value
of the remote's `annex.url`.

Support for this first appeared in git-annex version 10.20240731. Users of
older git-annex won't be able to use the smart http server, but can still
clone the repository from the dumb http server.