1
2
3
4
5
6
7
8
9
10
11
12
13
14
15
16
17
18
19
20
21
22
23
24
25
26
27
28
29
30
31
32
33
34
35
36
37
38
39
40
41
42
43
44
45
46
47
48
49
50
51
52
53
54
|
;;; guix-forge --- Guix software forge meta-service
;;; Copyright © 2023 Arun Isaac <arunisaac@systemreboot.net>
;;;
;;; This file is part of guix-forge.
;;;
;;; guix-forge is free software: you can redistribute it and/or modify
;;; it under the terms of the GNU General Public License as published
;;; by the Free Software Foundation, either version 3 of the License,
;;; or (at your option) any later version.
;;;
;;; guix-forge is distributed in the hope that it will be useful, but
;;; WITHOUT ANY WARRANTY; without even the implied warranty of
;;; MERCHANTABILITY or FITNESS FOR A PARTICULAR PURPOSE. See the GNU
;;; General Public License for more details.
;;;
;;; You should have received a copy of the GNU General Public License
;;; along with guix-forge. If not, see
;;; <https://www.gnu.org/licenses/>.
(use-modules (doc skribilo))
(document :title "guix-forge"
(p [,(emph [guix-forge]) is a Guix service that lets you run a complete ,(ref :url "https://en.wikipedia.org/wiki/Forge_(software)" :text "software forge") in the manner of GitHub, GitLab, etc. Unlike other free software forges such as GitLab, Gitea, etc., ,(emph [guix-forge]) is not a monolith but is an assemblage of several pieces of server software wired up to function as one. In this sense, it is a ,(emph [meta-service]) . ,(emph [guix-forge]) does for software forges what ,(ref :url "https://mailinabox.email/" :text "Mail-in-a-Box") does for email.])
(p [,(emph [guix-forge]) integrates the following software components:])
(itemize
(item [,(code "[X]") ,(ref :url "https://git.zx2c4.com/cgit/" :text "cgit") and ,(ref :url "https://github.com/jonashaag/klaus/" :text "klaus") (pick your favourite) to serve project git repositories on the web])
(item [,(code "[X]") ,(ref :url "https://laminar.ohwg.net" :text "laminar") for continuous integration])
(item [,(code "[X]") ,(ref :url "https://github.com/ndilieto/uacme/" :text "uacme") and ,(ref :url "https://gnutls.org/" :text "gnutls") for automatic provision and renewal of TLS certificates via ACME])
(item [,(code "[ ]") web server to serve static project sites])
(item [,(code "[ ]") ,(ref :url "https://public-inbox.org/README.html" :text "public-inbox") for project discussions]))
(p [A choice of different software components may be offered provided it does not complicate the interface too much.])
(p [,(emph [guix-forge]) is provided on a best effort basis. Its design is unstable, and open to change. We will try our best to not break your system configuration often, but it might happen.])
(section :title "Installation"
:number #f
(p [,(emph [guix-forge]) is distributed as a Guix channel. To use it, add the following channel definition to your ,(file [~/.config/guix/channels.scm]) file.])
(prog [(channel
(name 'guix-forge)
(url "https://git.systemreboot.net/guix-forge/")
(branch "main")
(introduction
(make-channel-introduction
"0432e37b20dd678a02efee21adf0b9525a670310"
(openpgp-fingerprint
"7F73 0343 F2F0 9F3C 77BF 79D3 2E25 EE8B 6180 2BB3"))))]
:line #f))
(section :title "Documentation"
:number #f
(p [The ,(ref :url "/manual/dev/en/" :text "guix-forge manual") is available online.]))
(section :title "Philosophy"
:number #f
(p [In order to empower ordinary users, software should not just be free (as in freedom), but also be simple and easy to deploy, especially for small-scale deployments. ,(emph [guix-forge]) is therefore minimalistic, and does not require running large database servers such as MariaDB and PostgreSQL.])
(p [While some state is inevitable, server software should strive to be as stateless as an old analog television set. You switch it on, and it works all the time. There are no pesky software updates, and complex hidden state. ,(emph [guix-forge]) tries to be as stateless as possible. Almost all of /guix-forge's/ state can be version controlled, and the rest are simple files that can be backed up easily.])
(p [,(ref :url "https://drewdevault.com/2018/07/23/Git-is-already-distributed.html" :text "Git is already federated and decentralized") with email. ,(emph [guix-forge]) acknowledges this and prefers to support git's ,(ref :url "https://drewdevault.com/2018/07/02/Email-driven-git.html" :text "email driven workflow") with project discussion, bug reports and patches all happening over email.])
(p [,(emph [guix-forge]) is opinionated and will not expose all features provided by the software components underlying it. Keeping configuration options to a minimum is necessary to help casual users deploy their own forge, and to reduce the likelihood of configuration bugs.])))
|
