socle

README: document baseurl and the Go modules story

commit ff73f22ec0c2e27127cfc762383a73af4ae08887 · parent 52092f45a7 · browse this tree
Ximianth, 2026-10-27 17:08:21 UTC

diff --git a/README.md b/README.md
index cedc064..7daf147 100644
--- a/README.md
+++ b/README.md
@@ -20,6 +20,7 @@ socle takes exactly one config file, via the required `-config` flag
 The format is YAML:
 
 ```yaml
+baseurl: https://code.example
 repos:
   parnass:
     path: "%"
@@ -28,6 +29,12 @@ repos:
     description: "deploy scripts"
 ```
 
+- `baseurl` (optional) is the canonical outside address of this socle:
+  an absolute http(s) URL naming only a host.
+  When set, it becomes the displayed clone URL
+  (otherwise that's derived from each request, which a rewriting proxy can fool)
+  and enables serving Go vanity imports (see Go modules below).
+
 - `repos` maps URL names to local git repositories.
   A name may contain slashes, so the URL space can have depth.
   Name segments are limited to `[A-Za-z0-9._-]`, with no leading dot or dash,
@@ -84,6 +91,25 @@ a trailing `.git` on the URL also works, since git clients and habits both produ
 There is no push: socle never runs anything but read-only git subcommands,
 and a push attempt is refused explicitly.
 
+Go modules
+----------
+
+With `baseurl` configured, repos are `go get`-able under their socle URLs as vanity import paths:
+
+```
+go get code.example/name
+```
+
+socle answers the toolchain's `?go-get=1` probes with the `go-import` meta tag
+(pointing at its own clone URL, so the fetch is the ordinary smart-HTTP transport above)
+and a `go-source` tag, so pkg.go.dev links source views back to socle's tree pages.
+The repo's `go.mod` must of course declare the matching module path, `code.example/name`.
+
+Without `baseurl` this is all inert: an import prefix is a public claim
+that ends up in module caches and trackers, so socle only makes it on purpose.
+Note the go toolchain requires https on the probe (barring `GOINSECURE`),
+so in practice this means socle behind a TLS-terminating proxy.
+
 Rendering and theming
 ---------------------
 
@@ -102,7 +128,8 @@ Known limits
 - Branch and tag names containing `/` aren't addressable in URLs (they still work by sha),
   and the accepted ref charset is narrower than git's own rules.
 - The log page shows the newest 100 commits; there is no pagination past that.
-- The clone URL on a repo's home page reflects the scheme and host of the direct request;
+- Without `baseurl` configured, the clone URL on a repo's home page reflects
+  the scheme and host of the direct request;
   behind a rewriting or TLS-terminating proxy it would be wrong.
 
 Deployment