Differences between revisions 8 and 25 (spanning 17 versions)
⇤ ← Revision 8 as of 2022-09-09 15:53:06 →
Size: 6094
Editor: DominicRicottone
Comment:
← Revision 25 as of 2025-12-19 21:38:51 → ⇥
Size: 4599
Editor: DominicRicottone
Comment: Removing mercurial stuff
Deletions are marked like this. Additions are marked like this.
Line 2: Line 2:

'''Sourcehut''' is a software system providing [[Git|git]] version control hosts, a bug tracker, and a simple web UI.
Line 11: Line 13:
Upstream only officially supports [[Linux/AlpineLinux|Alpine Linux 3.15]].

To enable the package repository, add the following line to `/etc/apk/repositories`. It '''must''' be the '''first''' repository checked.

{{{
https://mirror.sr.ht/alpine/v3.15/sr.ht
}}}

The community package repository must be enabled. See [[Linux/AlpineLinux#Software_Installation|here]] for more details.

Install the packager's key and update the package index.

{{{
wget -q -O /etc/apk/keys/[email protected] https://mirror.sr.ht/alpine/[email protected]
apk update
}}}

Sourcehut is a modular ecosystem, with `meta.sr.ht` being the only mandatory package (as it handles authentication and authorization). For example, to run the [[Git|git]] and [[Mercurial|mercurial]] services, use `git.sr.ht` and `hg.sr.ht`, respectively. Installation and configuration of these modular services is detailed in a corresponding section under Administration.

Install the `meta.sr.ht` package. Start and enable three services: `meta.sr.ht`, `meta.sr.ht-api`, and `meta.sr.ht-webhooks`. Finally enable the `metasrht-daily` cronjob and set it to run daily.



=== Community Packages ===

Eli Schwartz maintains a set of packages for [[Linux/ArchLinux|Arch Linux]].

Add the mirror to `/etc/pacman.conf`:

{{{
[sr.ht]
Server = https://mirror.sr.ht/archlinux/sr.ht
}}}

Then install the packagers' keys:

{{{
sudo pacman-key --recv-keys C0AAFC1676BD998617C94C42DC59670F1EB0A189
sudo pacman-key --lsign-key C0AAFC1676BD998617C94C42DC59670F1EB0A189
}}}



=== Development Setup ===

TODO: copy from [[https://emersion.fr/blog/2021/setting-up-sr.ht-for-local-development/]]		 Upstream only officially supports [[Linux/Alpine|Alpine Linux]] on AMD64 (a.k.a. x86_64) hardware. The software is made available through [[Linux/Alpine/Apk#Repositories|custom package repositories]]. Enable the community repository and `https://mirror.sr.ht/alpine/v3.17/sr.ht` (matching the Alpine Linux version of the host). Also install the [[Linux/Alpine/Apk#Signing_Keys|packaging key]] from `https://mirror.sr.ht/alpine/[email protected]`.
Line 62: Line 19:
== Configuration == == Setup and Configuration ==
Line 64: Line 21:
Several Sourcehut services depend on additional local services. Sourcehut is a modular system, with `meta.sr.ht` being the only mandatory package.

Start and enable three services: `meta.sr.ht`, `meta.sr.ht-api`, and `meta.sr.ht-webhooks`. Finally enable the `metasrht-daily` cronjob and set it to run daily.
Line 68: Line 27:
=== SMTP === === Web Server ===
Line 70: Line 29:
TODO: copy from [[https://drewdevault.com/2018/08/05/Local-mail-server.html]] A reverse proxy is needed to dispatch between services; to serve static content; and to serve the HTTP [[Git|git]] frontend. See [[Sourcehut/WebServer|Web Server]] for configuration information.
Line 72: Line 31:
With a running MTA, update the `mail` section of the Sourcehut configuration.
Line 74: Line 32:
{{{
[mail]
smtp-host=localhost
smtp-port=25
smtp-from=root@localhost
smtp-encryption=insecure
smtp-auth=none
smtp-user=
smtp-password=
Line 84: Line 33:
error-to=root@localhost
error-from=root@localhost		 === Mail Server ===
Line 87: Line 35:
pgp-privkey=/etc/sr.ht/pgp.key
pgp-pubkey=/etc/sr.ht/pgp.pubkey
pgp-key-id=mykeyid
}}}		 Several of the modular services have a direct dependency on a mail server; chiefly the mailing lists (`lists.sr.ht`) and the issue tracker (`todo.sr.ht`). The core system is also tightly integrated on email for critical reports.
Line 92: Line 37:
If encryption is necessary, try: See [[Sourcehut/Mail|Mail]] for configuration information.
Line 94: Line 39:
{{{
smtp-encryption=starttls
}}}

If authentication is necessary, try:

{{{
smtp-auth=plain
smtp-user=myuser
smtp-password=mypassword
}}}

The PGP settings are also mandatory to update. The private key must be a password-less file. `pgp-key-id` should be set to the key's ID string.

{{{
# need to remove passwords
# at gpg> prompt...
# type 'passwd'
# enter current password and leave new password blank
# read and agree to security warnings
gpg --edit-key KEYID

gpg --armor --export-options export-minimal --export KEYID >pgp.pubkey
gpg --armor --export-secret-key KEYID >pgp.key
}}}

For the `todo.sr.ht-lmtp` service, edit the `todo.sr.ht::mail` section of the Sourcehut configuration.

{{{
[todo.sr.ht::mail]
sock=/tmp/todo.sr.ht-lmtp.sock
sock-group=postfix
posting-domain=localhost.localdomain
}}}

To test the configuration, add an SSH key to the admin user. An automatic notification email will be generated by that trigger.		 A test email can be sent from `https://meta.example.com/privacy`.
Line 135: Line 45:
[[Redis]] will work out of the box. Simply ensure that the Sourcehut configuration can reach the service. The pools of web workers are managed through [[Redis]] queues. The connection string needs to be set in several parts of the configuration file.
Line 139: Line 49:
...
Line 142: Line 51:
[git.sr.ht]
...		 [meta.sr.ht]
Line 146: Line 54:
[meta.sr.ht]
...
webhooks=redis://localhost:6379/1

[todo.sr.ht]
...		 [git.sr.ht]
Line 155: Line 58:
Note that each service ''can'' use an independent database if desired. ''(And so on.)'' Note that each service ''can'' use an independent database if desired.
Line 161: Line 64:
=== SSH ===

SSH access to hosted repositories is a recurring challenge for git services. Sourcehut's approach is to insert an authentication dispatch into the host's `sshd(8)` configuration.

In `/etc/ssh/sshd_config`, set:		 Each services is backed by a [[PostgreSQL]] database. The connection string needs to be set in several parts of the configuration file.
Line 168: Line 67:
AuthorizedKeysCommand=/usr/bin/gitsrht-dispatch "%u" "%h" "%t" "%k"
AuthorizedKeysCommandUser=root
PermitUserEnvironment SRHT_*		 [git.sr.ht]
connection-string=postgresql://postgres@localhost:5432/git.sr.ht?sslmode=disable
migrate-on-upgrade=yes

[meta.sr.ht]
connection-string=postgresql://postgres@localhost:5432/meta.sr.ht?sslmode=disable
migrate-on-upgrade=yes
Line 173: Line 76:
A `git` user is created automatically by installing `git.sr.ht`, but an additional step of setting a login password is necessary. Note that each service ''can'' use an independent database instance if desired.
Line 175: Line 78:
{{{
sudo passwd git
}}}
Line 179: Line 79:
When a user pulls to `[email protected]:~username/reponame`, `gitsrht-dispatch` will parse the `git.sr.ht::dispatch` section of the Sourcehut configuration.
Line 181: Line 80:
{{{
[git.sr.ht::dispatch]
/usr/bin/gitsrht-keys=git:git
/usr/bin/buildsrht-keys=builds:builds
}}}		 === Git ===
Line 187: Line 82:
The right-hand side is the uid-gid pair that `gitsrht-dispatch` will scan for, and the left-hand side is a binary that will be dispatched to. Additional authentication stacks can be inserted here. If no dispatcher matches, `gitsrht-dispatch` just looks up the user's `authorized_users` file, to ensure that normal SSH access is uninterrupted. Install `git.sr.ht`. Start and enable three services: `git.sr.ht`, `git.sr.ht-api`, and `git.sr.ht-webhooks`.
Line 189: Line 84:
`gitsrht-keys` will then 'generate' an `authorized_users` file based on the Sourcehut database of who should have access to the corresponding repository. This `authorized_users` file is then piped back to `sshd(8)` for normal key-based authentication. On the server side, this looks like the `git` user pulling from its `$HOME` directory (typically `var/lib/git`). A [[Protocols/CGI#FastCGI|FastCGI]] server needs to be setup to handle the HTTP-based [[Git|git]] requests. Similarly, an [[Encryption/SSH|SSH]] server is needed for SSH-based requests. See [[Sourcehut/SSH#Setup|here]] for details on configuring the latter.

Finally enable the `gitsrht-periodic` cronjob and set it to run regularly.

Also see [[Sourcehut/WebServer#Git|here]] to update the web server with content relating to the git service.



=== Issue Tracker ===

Install `todo.sr.ht`. Start and enable three services: `todo.sr.ht`, `todo.sr.ht-api`, `todo.sr.ht-lmtp`, and `todo.sr.ht-webhooks`.

Configure the mail server to route issue tracker mail to the [[Email/LMTP|LMTP]] server. See [[Sourcehut/Mail#LMTP_Servers|here]] for details.

Also see [[Sourcehut/WebServer#Todo|here]] to update the web server with content relating to the issue tracker.
Line 207: Line 116:
Note that admin users will permanently see a 'PRODUCTION ENVIRONMENT' banner on all pages.

With an existing admin user, users can be managed in the web UI.

Individual users then need to upload their own SSH and PGP keys, also through the web UI.
Line 210: Line 125:

=== Mercurial ===
Line 227: Line 140:
----



== See also ==

[[https://man.sr.ht/installation.md|Upstream guidance for installing and hosting]]

Sourcehut

Sourcehut is a software system providing git version control hosts, a bug tracker, and a simple web UI.

Contents

  1. Sourcehut
    1. Installation
    2. Setup and Configuration
      1. Web Server
      2. Mail Server
      3. Redis
      4. PostgreSQL
      5. Git
      6. Issue Tracker
    3. Administration
      1. Users
      2. Git
      3. Bug Tracker
      4. Page Hosting
      5. Mail Lists
      6. Automated Builds
    4. See also

Installation

Upstream only officially supports Alpine Linux on AMD64 (a.k.a. x86_64) hardware. The software is made available through custom package repositories. Enable the community repository and https://mirror.sr.ht/alpine/v3.17/sr.ht (matching the Alpine Linux version of the host). Also install the packaging key from https://mirror.sr.ht/alpine/[email protected].

Setup and Configuration

Sourcehut is a modular system, with meta.sr.ht being the only mandatory package.

Start and enable three services: meta.sr.ht, meta.sr.ht-api, and meta.sr.ht-webhooks. Finally enable the metasrht-daily cronjob and set it to run daily.

Web Server

A reverse proxy is needed to dispatch between services; to serve static content; and to serve the HTTP git frontend. See Web Server for configuration information.

Mail Server

Several of the modular services have a direct dependency on a mail server; chiefly the mailing lists (lists.sr.ht) and the issue tracker (todo.sr.ht). The core system is also tightly integrated on email for critical reports.

See Mail for configuration information.

A test email can be sent from https://meta.example.com/privacy.

Redis

The pools of web workers are managed through Redis queues. The connection string needs to be set in several parts of the configuration file. 

[sr.ht]
redis-host=redis://localhost

[meta.sr.ht]
webhooks=redis://localhost:6379/1

[git.sr.ht]
webhooks=redis://localhost:6379/1

(And so on.) Note that each service can use an independent database if desired.

PostgreSQL

Each services is backed by a PostgreSQL database. The connection string needs to be set in several parts of the configuration file. 

[git.sr.ht]
connection-string=postgresql://postgres@localhost:5432/git.sr.ht?sslmode=disable
migrate-on-upgrade=yes

[meta.sr.ht]
connection-string=postgresql://postgres@localhost:5432/meta.sr.ht?sslmode=disable
migrate-on-upgrade=yes

Note that each service can use an independent database instance if desired.

Git

Install git.sr.ht. Start and enable three services: git.sr.ht, git.sr.ht-api, and git.sr.ht-webhooks.

A FastCGI server needs to be setup to handle the HTTP-based git requests. Similarly, an SSH server is needed for SSH-based requests. See here for details on configuring the latter.

Finally enable the gitsrht-periodic cronjob and set it to run regularly.

Also see here to update the web server with content relating to the git service.

Issue Tracker

Install todo.sr.ht. Start and enable three services: todo.sr.ht, todo.sr.ht-api, todo.sr.ht-lmtp, and todo.sr.ht-webhooks.

Configure the mail server to route issue tracker mail to the LMTP server. See here for details.

Also see here to update the web server with content relating to the issue tracker.

Administration

Users

To create an admin user, try: 

metasrht-manageuser -t admin -e <email> <username>

Note that admin users will permanently see a 'PRODUCTION ENVIRONMENT' banner on all pages.

With an existing admin user, users can be managed in the web UI.

Individual users then need to upload their own SSH and PGP keys, also through the web UI.

Git

Bug Tracker

Page Hosting

Mail Lists

Automated Builds

Anecdotally the build service is the most unreliable component of the Sourcehut ecosystem.

The master server runs the builds.sr.ht package and service. Each runner corresponds to a builds.sr.ht-worker service, which depends on the builds.sr.ht-worker and builds.sr.ht-images packages.

Upstream's production architecture thoroughly encapsulates the runners.

See also

Upstream guidance for installing and hosting

CategoryRicottone

Sourcehut (last edited 2025-12-19 21:38:51 by DominicRicottone)