gitreef

A GIT over SSH server implemented using fish.
Log | Files | Refs | README | LICENSE

README.md (3169B)

      1 # GitReef
      2 
      3 Welcome to **gitreef** — a GIT over SSH server implemented using fish.
      4 
      5 The goal of this project is to provide a **minimal Git server** with no unnecessary features or management overhead.
      6 It’s designed for everyone who doesn’t need or want a fancy GUI or advanced functionality beyond the essentials.
      7 As a result, it’s **small, secure, fast**, and uses **under 10 MB of memory**, so it runs easily even on less powerful hardware like a **Raspberry Pi**.
      8 
      9 ---
     10 
     11 ## Features
     12 
     13 - 🐳 **Dockerized**
     14 - ⚙️ **Simple configuration** via command line or Docker Compose
     15 - 🚀 **Fast & secure**, with minimal dependencies: Git, SSH, Fish, Tini, Sudo
     16 - 👥 **Built-in user and repository management**
     17 - 🔐 **Basic ACL system** with per-user read/write permissions
     18 - 📜 **Logging**
     19 
     20 ---
     21 
     22 ## Security
     23 
     24 Keeping your repositories safe from unauthorized access is a top priority.
     25 This server applies multiple hardening and sandboxing measures, such as:
     26 
     27 - Minimal Alpine base image with only essential tools installed
     28 - Only **public-key authentication** (no passwords)
     29 - **No TTY and no interactive shell logins**
     30 - All Git commands are **sanitized and validated**
     31 - Repositories are stored under `/srv/repos` and cannot access paths outside that directory
     32 - Per-user **ACL file** checks permissions for each operation
     33 - **Root and “git” user logins are disabled**
     34 
     35 ---
     36 
     37 ## Examples
     38 
     39 ### Command Line
     40 ```sh
     41 docker run --rm -p "2222:22" jarlucmat/gitreef -u "user1:ecdsa-sha2-nistp256 AAAAE2VjZHNhLXNoYTItbmlzdHAyNTYAAAAIbm
     42 lzdHAyNTYAAABBBPsl91WPAT8aWwZ6y5WAfXU9PoHzxJ3YG9uFgSmlGQr2HwV+gL/XaTBJ4Brj+pa+R7tfYEBMi+7Navx/ZsEmr9E= mj@xps15" -r "/repo1.git;user1:w"
     43 ```
     44 
     45 ### Docker Compose
     46 Docker Compose:
     47 ```yaml
     48 services:
     49   gitreef:
     50     image: jarlucmat/gitreef
     51     ports:
     52       - "2222:22"
     53     environment:
     54       # Note: Variable names cannot contain dashes, but values can!
     55       # UID/GID of the user that owns all repositories
     56       - GIT_UID=1000
     57       - GIT_GID=1000
     58 
     59       # Users in the form USER_<id>=<username>:<ssh-public-key>
     60       - USER_user1=user1:ecdsa-sha2-nistp256 AAAAE2VjZHNhLXNoYTItbmlzdHAyNTYAAAAIbmlzdHAyNTYAAABBBPsl91WPAT8aWwZ6y5WAfXU9PoHzxJ3YG9uFgSmlGQr2HwV+gL/XaTBJ4Brj+pa+R7tfYEBMi+7Navx/ZsEmr9E= mj@xps15
     61       - USER_user2=user2:ecdsa-sha2-nistp256 AAAAE2VjZHNhLXNoYTItbmlzdHAyNTYAAAAIbmlzdHAyNTYAAABBBPsl91WPAT8aWwZ6y5WAfXU9PoHzxJ3YG9uFgSmlGQr2HwV+gL/XaTBJ4Brj+pa+R7tfYEBMi+7Navx/ZsEmr9E= mj@xps15
     62 
     63       # Repositories in the form REPO_<id>=<path>;<user>:<perm>[;<user2>:<perm>;...]
     64       # Permissions:
     65       #   r = read
     66       #   w = write
     67       # A user without a permission flag has read access by default.
     68       - REPO_repo1=/repo1.git;user1
     69       - REPO_repo2=/repo2.git;user2:w
     70       - REPO_repo3=/repo3.git;user1:r;user2:w
     71 
     72     volumes:
     73       # Basic volumes that should be mapped
     74       - ./ssh:/var/ssh
     75       - ./repos:/srv/repos
     76       - ./log:/var/log
     77 ```
     78 
     79 ## Notes
     80 
     81 You can use any SSH key type supported by Git and your base system. Logs are written to /var/log/git-run by default. ACL files and repository definitions are recreated automatically on container restart.
     82 
     83 ## License
     84 
     85 GPLv3 © 2025 Matthias Jaros