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
55
56
57
58
59
60
61
62
63
64
65
66
67
68
69
70
71
72
73
74
75
76
77
78
79
80
81
82
83
84
85
86
87
88
89
90
91
92
93
94
95
96
97
98
99
100
101
102
103
104
105
106
107
108
109
110
111
112
113
114
115
116
117
118
119
120
121
122
123
124
125
126
127
|
;;; guix-forge --- Guix software forge meta-service
;;; Copyright © 2022 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]
(chapter :title [Introduction]
(p [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., 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"). guix-forge does for software forges what ,(ref
:url "https://mailinabox.email/" :text "Mail-in-a-Box") does for
email.])
(p [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 [Philosophy]
(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. 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. 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. 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.])))
(chapter :title [Reference]
(description
(record-documentation "forge/forge.scm" '<forge-configuration>
(record-field "projects"
[List of ,(ref :mark "<forge-project>" :text
(code [<forge-project>])) objects describing projects managed by
guix-forge]))
(record-documentation "forge/forge.scm" '<forge-project>
(record-field "name"
[Name of the project])
(record-field "repository"
[Path to a local git repository, or URI to a remote git
repository])
(record-field "user"
[User who owns the repository if it is local. This field is
disregarded if the repository is remote.])
(record-field "description"
[Short one-line description of the project. It is used to set
the ,(file "description") file in the repository and will appear in
the cgit web interface.])
(record-field "website-directory"
[Path to the document root of the project website. Its
ownership is granted to the ,(code "laminar") user so that continuous
integration jobs can write to it.])
(record-field "ci-jobs"
[List of ,(ref :mark "<forge-laminar-job>") objects
describing ,(abbr :short "CI" :long "continuous integration") jobs to
configure])
(record-field "ci-jobs-trigger"
[One of ,(code ['post-receive-hook]), ,(code ['webhook]), or
,(code ['cron]) representing the type of trigger for continuous
integration jobs.
,(description
(item :key (code ['post-receive-hook])
[If ,(code ['post-receive-hook]) is specified, the ,(file
"post-receive-hook") of the repository is configured to trigger CI
jobs. This is possible only for local repositories. Note that any
pre-existing ,(file "post-receive-hook") is overwritten.])
(item :key (code ['webhook]) [If ,(code
['webhook]) is specified, a webhook server is configured to trigger CI
jobs when a request is received on ,(samp "http://hostname:port/hooks/<name>") \.])
(item :key (code ['cron]) [If ,(code ['cron]) is
specified ,a cron job triggers the CI jobs once a day.]))]
:default [,(code ['post-receive-hook]) for local repositories
and ,(code ['cron]) for remote repositories])
(record-field "repository-branch"
[Main branch of the repository. This field is currently
unused unused, and may be deprecated in the future.]))
(record-documentation "forge/laminar.scm" '<forge-laminar-job>
(record-field "name"
[Name of the job])
(record-field "run"
[G-expression to be run])
(record-field "after"
[G-expression to be run after the main job script]))
(record-documentation "forge/webhook.scm" '<webhook-configuration>
(record-field "package"
[,(code [webhook]) package to use])
(record-field "ip"
[IP address to listen on])
(record-field "port"
[Port to listen on])
(record-field "log-directory"
[Directory to write log files to])
(record-field "hooks"
[List of ,(ref :mark "<webhook-hook>" :text (code
[<webhook-hook>])) objects describing hooks to configure]))
(record-documentation "forge/webhook.scm" '<webhook-hook>
(record-field "id"
[Identifier of the webhook. This hook is triggered at ,(ref
:url [http://host:port/hooks/<id>]).])
(record-field "run"
[G-expression to run when the webhook is triggered])))))
|
