commit 07841caad7f2684ab466d7aec9e2b5a7dd5dd027
parent d39e93d64813389b674da467d9b32a8bddb19f3b
Author: Andreas Gruhler <andreas.gruhler@adfinis.com>
Date: Sat, 5 Aug 2023 11:04:51 +0200
doc(git): update readme
Diffstat:
1 file changed, 44 insertions(+), 26 deletions(-)
diff --git a/hcl/default/git/README.md b/hcl/default/git/README.md
@@ -1,67 +1,85 @@
+Basic Usage
+-----------
+
+Register the volumes:
+
nomad volume register volume-git.hcl
nomad volume register volume-stagit.hcl
-The git server job runs several tasks with distinct purpose:
- * smarthttp - A Smart HTTP frontend for Git (Port 80)
- * stagit - A HTTP frontend to display static files (Port 80)
+Run the job:
+nomad job run -detach git.nomad
-Stagit Web Interface
---------------------
+The git server job runs several tasks with distinct purpose:
+* smarthttp - A Smart HTTP frontend for Git (Port 80)
+* stagit - A HTTP frontend to display static files (Port 80)
-- http://192.168.1.174:8018/
+Git on the Server
+-----------------
+Create `git-daemon-export-ok` file to make the repo public:
-- Explain `git-daemon-export-ok` file
+https://git-scm.com/book/en/v2/Git-on-the-Server-Git-Daemon
/srv/git # touch /srv/git/public/test.git/git-daemon-export-ok
-
If not set, results in "access denied" on clone (http/git):
-$ git clone git://192.168.1.174/public/test.git
+$ git clone git://$repo-host/public/test.git
Cloning into 'test'...
fatal: remote error: access denied or repository not exported: /test.git
-Or it also shows a 404 in Stagit Web UI (because static files are not created or removed).
+It also shows a 404 in Stagit Web UI (because static files are not created or removed).
+Stagit Web Interface
+--------------------
-- Explain url/description/owner files
+The following files describe a repo:
+* .git/url
+* .git/description
+* .git/owner
+This information is also rendered in Stagit web UI.
+More information can be found directly in the upstream documentation and the
+man page at https://git.codemadness.org/stagit.
-Explain where help for stagit can be found (man page, upstream url)
+To re-render the static html pages, run stagit CLI on the server:
$ nomad exec -task stagit d129cfa4 sh
/ # which stagit
/usr/local/bin/stagit
-- Explain `create.sh``file
- * Only generates the static fils when git-daemon-export-ok file exists
- * The repo will always be in the index, but 404 on the web interface if the file does not exist
- * The index will only show repos with at least 1 commit
-
/srv/git # /opt/stagit/create.sh
test... done
-The post-receive hook to updated on further changes is automatically added during `create.sh`.
+Some remarks on how that script works:
+* Only generates the static fils when git-daemon-export-ok file exists
+* The repo will always be in the index, but 404 on the web interface if the
+ file does not exist
+* The index will only show repos with at least 1 commit
+The post-receive hook to re-generate the static html files on further push
+changes to the repo is automatically added to the repo during `create.sh`.
SMART-HTTP read/write access
----------------------------
-Explain how to clone repos
-
-git clone http://192.168.1.174:8028/test.git
-git clone http://192.168.1.174:8028/test
+To clone repositories:
-- Explain that only HTTP with credentials has push access
-- Mention git-daemon-export-ok file for smarthttp clones
+git clone http://$repo-host:$repo-port/test.git
+git clone http://$repo-host:$repo-port/test
-Write access is only granted with Smart HTTP (HTTPS) protocol.
+Some remarks on how smart HTTP access works:
+* Cloning a repo still requires git-daemon-export-ok file. Read access is
+ granted when git-daemon-export-ok exists.
+* Write access is granted with Smart HTTP (HTTPS) protocol and BasicAuth
https://git-scm.com/book/en/v2/Git-on-the-Server-Smart-HTTP
+The user credentials for BasicAuth can be stored on the server. To create a new
+file for $user:
+
$ nomad exec -task smarthttp 1dc64f2f sh
-/ # htpasswd -c /srv/git/.htpasswd in0rdr
+/ # htpasswd -c /srv/git/.htpasswd $user
