~sircmpwn/sr.ht-docs

61dff648826303a902d35f9dd641f0a8d501cbc0 — Jason Phan 11 months ago 96ed093
Update hg.sr.ht installation/config pages
3 files changed, 72 insertions(+), 56 deletions(-)

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

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

# Cronjobs

- `hgsrht-periodic`: The recommended configuration is
  `*/20 * * * * hgsrht-periodic`.
- `hgsrht-clonebundles` (optional): It is recommend to run this job daily.

# Storage

## Repository

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

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

# SSH Dispatch

At the moment, hg.sr.ht uses git.sr.ht's SSH dispatcher, which you need to set
up as the system-wide SSH authorization hook. See git.sr.ht's [Configuration
page](/git.sr.ht/configuration.md) for more information.

Once this is done, you need to make the hg.sr.ht authorization hook be part of
the SSH dispatching, via the `hgsrht-keys` and `hgsrht-shell` scripts. See the
`[dispatch]` section of your hg.sr.ht configuration for more details.

Authorization logs are written to `hg-srht-shell`.

# HTTP(S) Cloning

hg.sr.ht does not do HTTP(S) cloning for you, so you'll need to set it up
yourself in Nginx. 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 ~ ^/[~^][a-z0-9_]+/[a-zA-Z0-9_.-]+/\.hg.*$ {
		auth_request /authorize;
		root /var/lib/mercurial;
}
```

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

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

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

M hg.sr.ht/installation.md => hg.sr.ht/installation.md +9 -56
@@ 1,68 1,21 @@
---
title: hg.sr.ht installation
title: hg.sr.ht Installation
---

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

# Installation

hg.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.
hg.sr.ht can be installed with the [standard package
installation process](/installation.md#installing-from-packages).

## Daemons

- `hg.sr.ht`: the web service
- `hg.sr.ht` - The web service.

## Cronjobs

- `hgsrht-periodic`: various maintenance tasks. Recommended configuration is
  `*/20 * * * * hgsrht-periodic`
- `hgsrht-clonebundles`: optional cronjob to generate [clone
  bundles][clonebundles]. Recommended to run daily, e.g.
  `0 * * * * hgsrht-clonebundles`

[clonebundles]: https://www.mercurial-scm.org/wiki/ClonebundlesExtension

Clone bundles are computationally expensive to create, and use up more disk
space, but may dramatically speed up clone operations on large repositories.

## Repository storage

You will need to set up a directory for repositories to be stored in - we
suggest `/var/lib/hg/`. Also configure a `hg` user and assign ownership over
`/var/lib/hg/` to this user. The hg.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 hg.sr.ht web application runs as this user.

## SSH dispatch

At the moment, hg.sr.ht uses git.sr.ht's SSH dispatcher, which you need to setup
as the system-wide SSH authorization hook. See the [git.sr.ht
documentation](../git.sr.ht/installation.md#ssh-dispatch) for more information.

Once this is done, you need to make the hg.sr.ht authorization hook be part of
the SSH dispatching, via the `hgsrht-keys` and `hgsrht-shell` scripts. See the
`[dispatch]` section of you hg.sr.ht configuration for details on how this
works.

Authorization logs are written to `hg-srht-shell`.

## HTTP(s) Cloning

hg.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 ~ ^/[~^][a-z0-9_]+/[a-zA-Z0-9_.-]+/\.hg.*$ {
		auth_request /authorize;
		root /var/lib/mercurial;
}
```
- `hgsrht-periodic`: Performs various maintenance tasks.
- `hgsrht-clonebundles` (optional): Generates [clone
  bundles](https://www.mercurial-scm.org/wiki/ClonebundlesExtension).