1 files changed, 105 insertions, 0 deletions
diff --git a/readme.md b/readme.md
new file mode 100644
index 0000000..172112e
--- /dev/null
+++ b/readme.md
@@ -0,0 +1,105 @@
+# Alpine Linux Cgit
+
+Docker image for running a cgit instance.
+
+Primarily designed for a single user though it wouldn't be too hard to alter
+the [`entrypoint.sh`](entrypoint.sh) to add and support multiple users with
+separate keys, permissions and such.
+
+This runs fastcgiwrap, nginx and a SSH server for a self hosted private
+git server.
+
+Password authentication for SSH is entirely disabled 
+
+## Building
+
+```shell
+$ docker build -t cgit .
+```
+
+## Configuration
+
+Mostly by environment variables:
+
+
+```bash
+# You can supply authorized keys via environment variables in addition
+# to adding them directly to git's home directory `.ssh/authorized_keys`
+# AUTHORIZED_KEYS="CHANGEME"
+SSHD_PORT="${SSHD_PORT:-8022}"
+NGINX_LISTEN="${NGINX_LISTEN:-8080}"
+# This is shown on the cgit user interface by default, you may
+# wish to change it
+FULL_NAME="${FULL_NAME:-Default Cgit User}"
+# Bash is installed by default, feel free to change this
+CGIT_SHELL="${CGIT_SHELL:-/bin/ash}"
+# UID and GID used by the `git` user inside of the container
+CGIT_UID="${CGIT_UID:-3500}"
+CGIT_GID="${CGIT_GID:-3500}"
+# Threads for fcgiwrap
+CGIT_THREADS="${CGIT_THREADS:-1}"
+# Where the SSH host keys will be stored, 
+SSH_HOST_KEY_DIR="${SSH_HOST_KEY_DIR:-/var/hostkeys/}"
+NGINX_WORKER_PROCESSES="${NGINX_WORKER_PROCESSES:-1}"
+NGINX_WORKER_CONNECTIONS="${NGINX_WORKER_CONNECTIONS:-1024}"
+```
+
+No SSL configuration is provided since it's expected that you will toss
+this behind a proxy.
+
+
+## Volumes / persistence
+
+By default there are no volumes, you will want to specify them for
+`/var/git` and `/var/hostkeys`
+
+`/var/git` is the home directory for git where you should put your
+repositories, cgit configuration, scripts and optionally your ssh
+keys
+
+`/var/hostkeys` is where the SSH server's host keys will be stored.
+If omitted new host keys will be generated on each run leading to
+some scary warnings since SSH is trust on first use and stores the host
+keys.
+
+
+## Examples
+
+
+### Calling docker directly
+
+```shell
+$ docker run -it --rm \
+    -e CGIT_UID=1000 \
+    -e CGIT_GID=1000 \
+    -e "AUTHORIZED_KEYS=$(cat ~/.ssh/id_ed25519.pub)" \
+    -v $(pwd)/homedir:/var/git \
+    -v $(pwd)/hostkeys:/var/hostkeys
+    cgit
+```
+
+
+### `docker-compose`
+
+
+`docker-compose.yml`
+```yaml
+version: '3'
+services:
+  cgit:
+    build:
+      context: .
+      image: cgit
+    volumes:
+      - ./homedir:/var/git
+      - ./hostkeys:/var/hostkeys
+    ports:
+      - '127.0.0.1:8080:8080'
+      - '0.0.0.0:8022:8022'
+```
+
+And then
+
+```shell
+$ docker-compose up -d
+```