= Sourcehut =

'''Sourcehut''' is a software system providing [[Git|git]] and [[Mercurial|mercurial]] version control hosts, a bug tracker, and a simple web UI.

<<TableOfContents>>

----



== Installation ==

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/alpine@sr.ht.rsa.pub`.

----



== 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|git]] frontend. See [[Sourcehut/WebServer|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 [[Sourcehut/Mail|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 [[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.

----



== 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 ===

=== Mercurial ===

=== 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 [[https://man.sr.ht/builds.sr.ht/configuration.md#security-model|thoroughly encapsulates]] the runners.

----



== See also ==

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



----
CategoryRicottone