1 files changed, 75 insertions, 0 deletions
diff --git a/readme.md b/readme.md
new file mode 100644
index 0000000..abf9829
--- /dev/null
+++ b/readme.md
@@ -0,0 +1,75 @@
+# cgit
+
+[Docker image](https://hub.docker.com/r/tvanbesi/cgit)
+
+This project is a [cgit](https://git.zx2c4.com/cgit/about/) docker image.
+
+It aims to be as simple as possible. No authentication, no SSH, just browsing repositories on a web page. The container doesn't write to the repositories so they can be read-only.
+
+# Build
+
+```
+docker build --tag cgit .
+```
+
+# Run
+
+## cgit configuration and runtime
+
+Examples are provided in the `examples` directory.
+
+* `CGITRC`: Host directory containing a `cgitrc` configuration, see [cgitrc manual](https://manpages.debian.org/trixie/cgit/cgitrc.5.en.html).
+* `COMMIT_FILTER`: Host directory containing an executable `commit-filter.sh`  script to format Git commit messages. See the `commit-filter` section of the [cgitrc manual](https://manpages.debian.org/trixie/cgit/cgitrc.5.en.html).
+* `ABOUT`: Host directory containing `about.md` for the front page "about" section.
+* `REPOSITORIES`: Host directory containing your Git repositories.
+
+## Run with `docker`
+
+```
+docker run \
+    --rm \
+    --name cgit \
+    --publish 8080:80 \
+    --mount type=bind,src=CGITRC,dst=/etc/cgit,ro \
+    --mount type=bind,src=COMMIT_FILTER,dst=/usr/local/lib/cgit/filters/commit \
+    --mount type=bind,src=ABOUT,dst=/srv/cgit,ro \
+    --mount type=bind,src=REPOSITORIES,dst=/srv/git,ro \
+    cgit
+```
+
+Browse the website [here](http://localhost:8080).
+
+## Run with `docker compose`
+
+*Example `compose.yaml`:*
+
+```
+services:
+  cgit:
+    build: .
+    image: cgit
+    container_name: cgit
+    ports:
+      - 8080:80
+    volumes:
+      - CGITRC:/etc/cgit:ro
+      - COMMIT_FILTER:/usr/local/lib/cgit/filters/commit
+      - ABOUT:/srv/cgit:ro
+      - REPOSITORIES:/srv/git:ro
+```
+
+Browse the website [here](http://localhost:8080).
+
+# Configuration
+
+## Repository specific `cgitrc`
+
+Add a `cgitrc` file at the root of a repository to configure it for cgit. Note that this only works with the `scan-path` setting.
+
+*Example `cgitrc`:*
+
+```
+desc=Repository description
+owner=Repository owner
+section=Repository section
+```