# mugit

mugit is a small, read-only web front end for a directory of bare git
repositories, with cloning over HTTPS. It is for the person who keeps
their own git server, pushes to it over SSH, and wants the public parts
of it to have a web page and a clone URL without running a forge.

What it does:

- lists the public repositories, with descriptions and last-commit dates;
- shows each repository's README, rendered from Markdown, and lets
  visitors browse the files on the default branch;
- serves `git clone` and `git fetch` over HTTP(S) through git's own
  smart protocol;
- obtains and renews its own Let's Encrypt certificate, or runs plain
  HTTP behind a reverse proxy.

What it does not do: 

- issues
- pull requests
- accounts
- pushing over HTTP
- anything else that writes. Repositories are managed with git itself, over SSH or on the machine.

## How repositories are published

mugit serves a single directory, `/srv/git` by default. Each bare
repository in it is a subdirectory named `<name>.git`. A name is the part
before `.git`: letters, digits, `.`, `_` and `-`, not starting with a dot
and not itself ending in `.git`.

A repository is public when it contains a file named
`git-daemon-export-ok`, the same convention git-daemon and
git-http-backend use. Everything else in the directory is invisible: a
private repository and a nonexistent one both answer with the same 404,
so the site never confirms which private names exist.

    cd /srv/git
    git init --bare widget.git
    echo "A widget for widgeting" > widget.git/description
    touch widget.git/git-daemon-export-ok

The `description` file, which git creates in every repository, is shown
on the index and the repository page. The README is looked for at the
root of the default branch, under the names `README.md`,
`README.markdown`, `README` and `README.txt`, in that order of
preference. Relative links and images in a Markdown README resolve into
the site's own file and raw views.

Bear in mind that publishing a repository publishes all of it: every
branch, tag and commit that a clone would fetch, not just the default
branch the web pages show.

## Building

mugit is a single Rust binary. It needs a Rust toolchain of 1.88 or
later, and the `git` command on the PATH at runtime for clones, fetches
and raw file downloads (everything else uses a bundled libgit2).

    cargo build --release

The binary is `target/release/mugit`. The stylesheet and favicon are
embedded in it, so it has no files to install alongside it.

## Running

Every option is a command line flag or an environment variable of the
same name with a `MUGIT_` prefix; `mugit --help` lists them all with
their defaults. The ones that matter:

| Flag | Environment | Default | Meaning |
|---|---|---|---|
| `--repos` | `MUGIT_REPOS` | `/srv/git` | The directory of bare repositories |
| `--listen` | `MUGIT_LISTEN` | `0.0.0.0:8000` | Address for plain HTTP |
| `--tls-domain` | `MUGIT_TLS_DOMAIN` | | Enables HTTPS with a Let's Encrypt certificate for this domain |
| `--tls-listen` | `MUGIT_TLS_LISTEN` | `0.0.0.0:443` | Address for HTTPS |
| `--acme-cache` | `MUGIT_ACME_CACHE` | `/var/lib/mugit/acme` | Where the ACME account key and certificates are kept |
| `--acme-contact` | `MUGIT_ACME_CONTACT` | | Contact email registered with the certificate authority |
| `--acme-staging` | `MUGIT_ACME_STAGING` | off | Use the Let's Encrypt staging environment while testing |
| `--site-name` | `MUGIT_SITE_NAME` | `mugit` | Name shown in page headers and titles |
| `--public-url` | `MUGIT_PUBLIC_URL` | | Base URL that clone URLs are built from |
| `--page-size` | `MUGIT_PAGE_SIZE` | `50` | Repositories per page of the index |
| `--git-processes` | `MUGIT_GIT_PROCESSES` | `8` | Git processes serving clones, fetches and raw files at once |
| `--git-idle-timeout` | `MUGIT_GIT_IDLE_TIMEOUT` | `60` | Seconds a stalled clone or download is tolerated before it is dropped |
| `--http-idle-timeout` | `MUGIT_HTTP_IDLE_TIMEOUT` | `300` | Seconds a silent connection is held before it is closed; must exceed twice `--git-idle-timeout` |

Logging goes to standard error. `MUGIT_LOG` takes a
[tracing filter](https://docs.rs/tracing-subscriber/latest/tracing_subscriber/filter/struct.EnvFilter.html)
such as `debug` or `mugit=debug,warn`; a release build logs warnings and
errors by default.

### Standalone with HTTPS

Give mugit a domain and it takes care of the certificate itself, using
the TLS-ALPN-01 challenge. That challenge is answered on port 443, so the
HTTPS listener must be reachable from the internet on that port, and the
plain listener then does nothing but redirect to HTTPS.

    mugit --tls-domain git.example.org --acme-contact you@example.org \
          --listen [::]:80 --tls-listen [::]:443

Clone URLs are built from `https://<domain>` unless `--public-url` says
otherwise. Try `--acme-staging` first if you are unsure of the setup:
Let's Encrypt rate-limits failed attempts against production.

### Behind a reverse proxy

Without a TLS domain, mugit speaks plain HTTP on the listen address and
leaves TLS to the proxy in front of it. Set `--public-url` to the address
visitors use, so that the clone URL shown on each page is right; without
it, mugit falls back to the scheme and Host header of each request.

    mugit --listen 127.0.0.1:8000 --public-url https://git.example.org

The proxy should pass requests through unbuffered: git's smart protocol
streams in both directions, and buffering a whole fetch would defeat the
bound mugit keeps on memory.

## Deploying as a service

A worked example for a Linux host with systemd, where repositories belong
to a `git` user that people push to over SSH, and mugit runs as its own
user with read-only access to them. Adjust paths and names to taste.

1. Create the service user and give it read access to the repositories
   through the `git` group. It owns nothing under the repository
   directory.

       useradd --system --home-dir /var/lib/mugit --shell /usr/sbin/nologin mugit
       usermod -aG git mugit
       chmod 750 /srv/git

   Repositories created by the `git` user need to be group-readable,
   which is git's default; check with `ls -l /srv/git/*.git` if in doubt.

2. Create the state directory for the ACME account key and certificates,
   and install the binary.

       install -d -m 750 -o mugit -g mugit /var/lib/mugit /var/lib/mugit/acme
       install -d -m 755 /opt/mugit
       install -m 755 target/release/mugit /opt/mugit/mugit

3. Install the unit from [`deploy/mugit.service`](deploy/mugit.service).
   It runs the binary from `/opt/mugit`, serves `/srv/git` on ports 80
   and 443, and hardens the process; everything specific to your site
   goes in `/etc/mugit/env`:

       install -m 644 deploy/mugit.service /etc/systemd/system/mugit.service
       install -d -m 755 /etc/mugit
       cat > /etc/mugit/env <<EOT
       MUGIT_TLS_DOMAIN=git.example.org
       MUGIT_ACME_CONTACT=you@example.org
       MUGIT_SITE_NAME=git.example.org
       EOT
       systemctl daemon-reload
       systemctl enable --now mugit

   For a reverse proxy setup, put `MUGIT_LISTEN=127.0.0.1:8000` and
   `MUGIT_PUBLIC_URL=https://git.example.org` in the file instead of the
   TLS domain.

4. Watch the journal for the first certificate:

       journalctl -u mugit -f

To upgrade, install the new binary over the old one and
`systemctl restart mugit`.

## Security notes

The visibility rule is the marker file and nothing else, so review a
repository's history before publishing it. The web side sanitises
rendered Markdown and sends every page with a Content Security Policy
that forbids script, and serves raw files with a sandbox policy and
types that browsers will not execute, so a hosted file cannot run on the
site's origin. Git processes are bounded in number and dropped when
their client stalls, which is the protection against clients that open
connections and never finish. There is no rate limiting beyond that; put
a proxy in front if you need it.

## Development

`cargo test` runs the unit tests and the integration tests under
`tests/`, which build temporary repositories and drive the site through
its HTTP API; one of them runs a real `git clone` against a live
listener. A local store for trying the site by hand is just a directory
of bare repositories:

    mkdir -p local/repos
    git clone --bare some/project local/repos/project.git
    touch local/repos/project.git/git-daemon-export-ok
    cargo run -- --repos local/repos --listen 127.0.0.1:8000

## License

This is free and unencumbered software released into the public domain
under the [Unlicense](LICENSE).