From 0565e5385abcf1b9cbbdf665007ddd8bbb5a8960 Mon Sep 17 00:00:00 2001
From: Max Resnick <max@ofmax.li>
Date: Sat, 29 Mar 2025 17:02:49 -0700
Subject: doc: update readme

---
 README.md | 87 ++++++++++++++++++++++++++++++++++++++++++++++++++++++++++++---
 1 file changed, 84 insertions(+), 3 deletions(-)

diff --git a/README.md b/README.md
index c109e41..63f4e6e 100644
--- a/README.md
+++ b/README.md
@@ -2,6 +2,8 @@
 
 `go-git-server` is an experimental web server that provides authentication and authorization for git repositories.
 
+An attempt at a secure Git HTTP server implementation in Go that provides authentication and authorization, inspired by Gitolite.
+
 ## Design
 
 Initially `go-git-server` wraps the built-in git-http-backend CGI process. This is done to provide complete compatibility out of the box. In the future a native go backend could be created but there's no compelling story to re-write the backend.
@@ -18,8 +20,87 @@ The current focus is for a single user and CI user(s) and intends to become self
 
 Tools like gitea are great, but they require things like a DBMS. This increases hosting comlexity and maintenance especially for small teams or single user bases.
 
+## Features
+
+- Git HTTP backend wrapper with authentication
+- Token-based authentication
+- Role-based access control using Casbin
+- Git repository management
+- Configuration via Git (optional management repo)
+- GitWeb support
+
+## Installation
+
+```bash
+# Clone the repository
+git clone https://git.ofmax.li/go-git-server
+cd go-git-server
+
+# Build the binary
+go build ./cmd/main.go
+```
+
+## Usage
+
+Start the server:
+
+```bash
+./main -r /path/to/repos -t tokens.csv -p policy.csv -m auth_model.ini
+```
+
+### Generate Authentication Token
+
+```bash
+./main -g
+```
+
+This will output a token and its hash. Add the hash to your tokens.csv file.
+
+## Configuration
+
+### Server Configuration (gitserver.yaml)
+
+```yaml
+name: "go-git-server"
+version: "v1alpha1"
+basepath: ./repos
+repos:
+  - name: myrepo
+    public: false
+    permissions:
+      - role: maintainers
+        mode: 1
+    git_web_config:
+      owner: username
+      description: Repository description
+```
+
+### Authentication Model (auth_model.ini)
+
+The authentication model uses Casbin for role-based access control.
+
+### Token File (tokens.csv)
+
+Format:
+```
+uid:username,hash
+```
+
+## Development
+
+Requirements:
+- Go 1.21+
+- Git
+
+Run tests:
+```bash
+go test ./...
+```
+
+## License
 
+This project is licensed under the MIT License - see the LICENSE file for details.
 
-# TODO
-- [ ] Refactor config to be a versioned model
-- [ ] hooks env?
\ No newline at end of file
+# TODO                                        
+- [ ] Refactor config to be a versioned model 
+- [ ] hooks env?                              
-- 
cgit v1.2.3