~sircmpwn/sr.ht-docs

96ed0932ee5f459e3a69493feea9b9ca4063fa92 — Jason Phan 10 months ago a3a50fd
Update git.sr.ht installation/config pages
3 files changed, 120 insertions(+), 91 deletions(-)

A git.sr.ht/configuration.md
A git.sr.ht/configuration_reference.md
M git.sr.ht/installation.md
A git.sr.ht/configuration.md => git.sr.ht/configuration.md +107 -0
@@ 0,0 1,107 @@
---
title: git.sr.ht Configuration
---

This document covers the configuration process for git.sr.ht.

# Cronjobs

- `gitsrht-periodic`: The recommended configuration is
  `*/20 * * * * gitsrht-periodic`.

# Storage

## Repository

<div class="alert alert-info">
  <strong>Note:</strong> If git.sr.ht was installed in a package, you may skip
  this section.
</div>

As a repository hosting service, git.sr.ht requires a place for storing
repositories (we recommend `/var/lib/git/`). It also requires a `git` user who
has ownership over the repository storage location.

## Objects

To allow users to upload artifacts to git repositories, an S3-compatible object
storage system may be set up and configured (separately from the repository
storage) before filling out the S3-related configuration options in your
`config.ini`.

<div class="alert alert-danger">
  <strong>Warning:</strong> You must secure the S3 storage to protect from
  unauthorized downloads of artifacts within private repositories. git.sr.ht
  will stream artifact downloads directly from the S3 storage after confirming
  authorization, so you simply need to avoid configuring the bucket for public
  access.
</div>

<div class="alert alert-info">
  <strong>Note:</strong> For object storage, we recommend
  <a href="https://min.io" class="alert-link">MinIO</a>,
  a free and open-source S3-compatible storage server.
</div>

# SSH Dispatch

It is necessary to configure git.sr.ht's SSH dispatcher as the system-wide SSH
authorization hook. First you need to install `go`, then build the dispatcher
with `go install` in the `gitsrht-dispatch` repository. The `gitsrht-shell`
helper is also written in Go, run the same process from its directory.

In `/etc/ssh/sshd_config`, configure gitsrht-dispatch like so:

    AuthorizedKeysCommand=/usr/bin/gitsrht-dispatch "%u" "%h" "%t" "%k"
    AuthorizedKeysCommandUser=root
    PermitUserEnvironment SRHT_*

`sshd` will invoke our dispatcher whenever a connection is made to the server
to obtain a list of authorized keys for the connecting user. The default
behavior is to read the `.ssh/authorized_keys` file from that user's HOME
directory, but the dispatcher can also "dispatch" to other authentication tools
for other users. This is used to authorize and perform git operations via the
`gitsrht-keys` and `gitsrht-shell`. See the `[dispatch]` section of your
git.sr.ht configuration for details on how this works and how to configure it
for additional services (e.g. man.sr.ht).

Authorization logs are written to `/var/log/gitsrht-dispatch` and
`gitsrht-shell`.

# HTTP(S) Cloning

git.sr.ht does not handle HTTP(S) cloning for you, so you'll need to set it up
yourself with your web server. Here's an example Nginx configuration:

```nginx
location = /authorize {
    proxy_pass http://127.0.0.1:5001;
    proxy_pass_request_body off;
    proxy_set_header Content-Length "";
    proxy_set_header X-Original-URI $request_uri;
}

location ~ ^/([^/]+)/([^/]+)/(HEAD|info/refs|objects/info/.*|git-upload-pack).*$ {
    auth_request /authorize;
    root /var/lib/git;
    fastcgi_pass unix:/run/fcgiwrap.sock;
    fastcgi_param SCRIPT_FILENAME /usr/lib/git-core/git-http-backend;
    fastcgi_param PATH_INFO $uri;
    fastcgi_param GIT_PROJECT_ROOT $document_root;
    fastcgi_param GIT_HTTP_EXPORT_ALL "";
    include fastcgi_params;
    gzip off;
}
```

It is important that you set up the `/authorize` endpoint to enforce the
privacy of private repositories.

If you don't have `/run/fcgiwrap.sock` on your system, you'll need to install
the `fcgiwrap` package.

<div class="alert alert-info">
  <strong>Note:</strong> On some systems, the script might be called
  `/run/fcgiwrap.socket`, `/run/fcgiwrap/fcgiwrap.sock`, or something else
  entirely. Consult your distribution's documentation.
</div>

A git.sr.ht/configuration_reference.md => git.sr.ht/configuration_reference.md +5 -0
@@ 0,0 1,5 @@
---
title: git.sr.ht Configuration Reference
---

This document covers the configuration options for the git.sr.ht service.

M git.sr.ht/installation.md => git.sr.ht/installation.md +8 -91
@@ 1,103 1,20 @@
---
title: git.sr.ht installation
title: git.sr.ht Installation
---

git.sr.ht is the git repository hosting service for the sr.ht network.
This document covers the installation steps for git.sr.ht, a git repository
hosting service.

# Installation

git.sr.ht is a standard sr.ht web service and can be installed through the
[standard procedure](/installation.md). However, there are several additional
steps required.
git.sr.ht can be installed through [package
installation](/installation.md#installing-from-packages).

## Daemons

- `git.sr.ht`: the web service
- `git.sr.ht-webhooks`: webhook delivery service
- `git.sr.ht` - The web service.
- `git.sr.ht-webhooks` - Webhook delivery service.

## Cronjobs

- `gitsrht-periodic`: various maintenance tasks. Recommended configuration is
  `*/20 * * * * gitsrht-periodic`

## Repository storage

You will need to set up a directory for repositories to be stored in - we
suggest `/var/lib/git/`. Also configure a `git` user and assign ownership over
`/var/lib/git/` to this user. The git.sr.ht package will automatically prepare
these for you. If you do not use the package, you must create the user yourself
and ensure that the git.sr.ht web application runs as this user.

## Object storage

To allow users to upload artifacts to git repositories, you need to configure an
S3-compatible object storage system separately, then fill out the s3-related
configuration options in config.ini. We recommend MinIO as a free-software
S3-compatible object storage server.

Please be aware that it is your responsibility to secure the S3 storage to
protect artifacts of private repositories from unauthorized downloads. git.sr.ht
will stream artifact downloads directly from S3 after confirming authorization,
so you simply need to avoid configuring the bucket for public access.

## SSH dispatch

It is necessary to configure git.sr.ht's SSH dispatcher as the system-wide SSH
authorization hook. First you need to install `go`, then build the dispatcher
with `go install` in the `gitsrht-dispatch` repository. The `gitsrht-shell`
helper is also written in Go, run the same process from its directory.


In `/etc/ssh/sshd_config`, configure gitsrht-dispatch like so:

```
AuthorizedKeysCommand=/usr/bin/gitsrht-dispatch "%u" "%h" "%t" "%k"
AuthorizedKeysCommandUser=root
PermitUserEnvironment SRHT_*
```

sshd will invoke our dispatcher whenever a connection is made to the server to
obtain a list of authorized keys for the connecting user. The default behavior
is to read the `.ssh/authorized_keys` file from that user's HOME directory, but
the dispatcher can also "dispatch" to other authentication tools for other
users. This is used to authorize and perform git operations via the
`gitsrht-keys` and `gitsrht-shell`. See the `[dispatch]` section of your
git.sr.ht configuration for details on how this works and how to configure it
for additional services (e.g. man.sr.ht).

Authorization logs are written to `/var/log/gitsrht-dispatch` and
`gitsrht-shell`.

## HTTP(s) Cloning

git.sr.ht does not do this for you - you need to wire it up in nginx. Here's an
example config:

```nginx
location = /authorize {
    proxy_pass http://127.0.0.1:5001;
    proxy_pass_request_body off;
    proxy_set_header Content-Length "";
    proxy_set_header X-Original-URI $request_uri;
}

location ~ ^/([^/]+)/([^/]+)/(HEAD|info/refs|objects/info/.*|git-upload-pack).*$ {
    auth_request /authorize;
    root /var/lib/git;
    fastcgi_pass unix:/run/fcgiwrap.sock;
    fastcgi_param SCRIPT_FILENAME /usr/lib/git-core/git-http-backend;
    fastcgi_param PATH_INFO $uri;
    fastcgi_param GIT_PROJECT_ROOT $document_root;
    fastcgi_param GIT_HTTP_EXPORT_ALL "";
    include fastcgi_params;
    gzip off;
}
```

It's important that you set up the `/authorize` endpoint to enforce the privacy
of private repositories.

If you don't have `/run/fcgiwrap.sock` on your system, you'll need to install
the `fcgiwrap` package (for instance: `apt-get install fcgiwrap`). On some
systems, the script might be `/run/fcgiwrap.socket` or
`/run/fcgiwrap/fcgiwrap.sock`.
- `gitsrht-periodic` - Performs various maintenance tasks.