diff options
| -rw-r--r-- | git.sr.ht/configuration.md | 107 | ||||
| -rw-r--r-- | git.sr.ht/configuration_reference.md | 5 | ||||
| -rw-r--r-- | git.sr.ht/installation.md | 99 |
3 files changed, 120 insertions, 91 deletions
diff --git a/git.sr.ht/configuration.md b/git.sr.ht/configuration.md new file mode 100644 index 0000000..092ab8d --- /dev/null +++ b/git.sr.ht/configuration.md @@ -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> diff --git a/git.sr.ht/configuration_reference.md b/git.sr.ht/configuration_reference.md new file mode 100644 index 0000000..a7a4b59 --- /dev/null +++ b/git.sr.ht/configuration_reference.md @@ -0,0 +1,5 @@ +--- +title: git.sr.ht Configuration Reference +--- + +This document covers the configuration options for the git.sr.ht service. diff --git a/git.sr.ht/installation.md b/git.sr.ht/installation.md index c86a309..71018c9 100644 --- a/git.sr.ht/installation.md +++ b/git.sr.ht/installation.md @@ -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. |