From a5c864482737af130afae42e32a51d316be61fb5 Mon Sep 17 00:00:00 2001 Message-ID: From: Ekaitz Zarraga Date: Thu, 7 Nov 2024 10:03:58 +0100 Subject: [PATCH v3] doc: Add "Contributing to Guix's infrastructure". MIME-Version: 1.0 Content-Type: text/plain; charset=UTF-8 Content-Transfer-Encoding: 8bit Use the "Call for contribution to the Guix infrastructure" by Ludovic Courtès to create a section in the documentation that describes how to contribute to the infrastructure. https://lists.gnu.org/archive/html/guix-devel/2024-05/msg00183.html * doc/contributing.texi (Contributing to Guix's infrastructure): New section. Change-Id: I3f3a99ad884110cc8323789e8c14bec1f7327e97 --- doc/contributing.texi | 193 ++++++++++++++++++++++++++++++++++++++++++ 1 file changed, 193 insertions(+) diff --git a/doc/contributing.texi b/doc/contributing.texi index 8b9aa82bc8..cf5dfd7cfb 100644 --- a/doc/contributing.texi +++ b/doc/contributing.texi @@ -39,6 +39,7 @@ Contributing * Deprecation Policy:: Commitments and tools for deprecation. * Writing Documentation:: Improving documentation in GNU Guix. * Translating Guix:: Make Guix speak your native language. +* Contributing to Guix's Infrastructure:: Make Guix ecosystem work better. @end menu @node Requirements @@ -3607,3 +3608,195 @@ Translating Guix be updated accordingly (see @file{website/i18n-howto.txt} for more information on the process). @end itemize + + +@cindex infrastructure +@node Contributing to Guix's Infrastructure +@section Contributing to Guix's Infrastructure + +Since its inception, the Guix project has always valued its autonomy, and that +reflects in its infrastructure: our servers run Guix System and exclusively +free software, and are administered by volunteers. + +Of course this comes at a cost and this is why we need contributions. Our hope +is to make infrastructure-related activity more legible so that maybe you can +picture yourself helping in one of these areas. + + +@menu +* Coding:: +* System Administration:: +* Day-to-Day System Administration:: +* On-Site Intervention:: +* Hosting:: +* Administrative Tasks:: +@end menu + +@node Coding +@subsection Coding + +Guix runs many Guix-specific services; this is all lovely Scheme code but it +tends to receive less attention than Guix itself: + +@itemize +@item Build Farm Front-End: @url{https://git.cbaines.net/guix/bffe, bffe} +@item Cuirass: @url{https://guix.gnu.org/cuirass/, Cuirass} +@item Goggles (IRC logger): +@url{https://git.savannah.gnu.org/cgit/guix/maintenance.git/tree/hydra/goggles.scm, +Goggles} +@item Guix Build Coordinator: +@url{https://git.savannah.gnu.org/cgit/guix/build-coordinator.git/, +Build-Coordinator} +@item Guix Data Service: +@url{https://git.savannah.gnu.org/git/guix/data-service.git/, Data-Service} +@item Guix Packages Website: +@url{https://codeberg.org/luis-felipe/guix-packages-website.git, +Guix-Packages-Website} +@item mumi: @url{https://git.savannah.gnu.org/cgit/guix/mumi.git/, Mumi} +@item nar-herder: @url{https://git.savannah.gnu.org/cgit/guix/nar-herder.git/, +Nar-Herder} +@item QA Frontpage: +@url{https://git.savannah.gnu.org/git/guix/qa-frontpage.git, Qa-Frontpage} +@end itemize + +There is no time constraint on this coding activity: any improvement is +welcome, whenever it comes. Most of these code bases are relatively small, +which should make it easier to get started. + +Prerequisites: Familiarity with Guile, HTTP, and databases. + +If you wish to get started, check out the README of the project of your choice +and get in touch with guix-devel and the primary developer(s) of the tool as +per @code{git shortlog -s | sort -k1 -n}. + +@node System Administration +@subsection System Administration + +Guix System configuration for all our systems is held in this repository: + +@url{https://git.savannah.gnu.org/cgit/guix/maintenance.git/tree/hydra/} + +The two front-ends are @file{berlin.scm} (the machine behind ci.guix.gnu.org) +and @file{bayfront.scm} (the machine behind bordeaux.guix.gnu.org, +guix.gnu.org, hpc.guix.info, qa.guix.gnu.org, and more). Both connect to a +number of build machines and helpers. + +Without even having SSH access to the machine, you can help by posting patches +to improve the configuration (you can test it with @code{guix system vm}). +Here are ways you can help: + +@itemize +@item +Improve infra monitoring: set up a dashboard to monitor all the infrastructure, +and an out-of-band channel to communicate about downtime. + +@item +Implement web site redundancy: guix.gnu.org should be backed by several +machines on different sites. Get in touch with us and/or send a patch! + +@item +Implement substitute redundancy: likewise, bordeaux.guix.gnu.org and +ci.guix.gnu.org should be backed by several head nodes. + +@item +Improve backup: there's currently ad-hoc backup of selected pieces over rsync +between the two head nodes; we can improve on that, for example with a +dedicated backup site and proper testing of recoverability. + +@item +Support mirroring: We'd like to make it easy for others to mirror substitutes +from ci.guix and bordeaux.guix, perhaps by offering public rsync access. + +@item +Optimize our web services: Monitor the performance of our services and tweak +nginx config or whatever it takes to improve it. + +There is no time constraint on this activity: any improvement is welcome, +whenever you can work on it. + +Prerequisite: Familiarity with Guix System administration and ideally with the +infrastructure handbook: + +@url{https://git.savannah.gnu.org/cgit/guix/maintenance.git/tree/doc/infra-handbook.org, +Infra-Handbook} + +@end itemize + +@node Day-to-Day System Administration +@subsection Day-to-Day System Administration + +We're also looking for people who'd be willing to have SSH access to some of +the infrastructure to help with day-to-day maintenance: restarting a build, +restarting the occasional service that has gone wild (that can happen), +reconfiguring/upgrading a machine, rebooting, etc. + +This day-to-day activity requires you to be available some of the time (during +office hours or not, during the week-end or not), whenever is convenient for +you, so you can react to issues reported on IRC, on the mailing list, or +elsewhere, and synchronize with other sysadmins. + +Prerequisite: Being a “known” member of the community, familiarity with Guix +System administration, with some of the services/web sites being run, and with +the infrastructure handbook: + +@url{https://git.savannah.gnu.org/cgit/guix/maintenance.git/tree/doc/infra-handbook.org, +Infra-Handbook} + +@node On-Site Intervention +@subsection On-Site Intervention + +The first front-end is currently generously hosted by the Max Delbrück Center +(MDC), a research institute in Berlin, Germany. Only authorized personnel can +physically access it. + +The second one, bordeaux.guix.gnu.org, is hosted in Bordeaux, France, in a +professional data center shared with non-profit ISP Aquilenet. If you live in +the region of Bordeaux and would like to help out when we need to go on-site, +please make yourself known by emailing @email{guix-sysadmin@@gnu.org}. + +On-site interventions are rare, but they're usually in response to an +emergency. + +@node Hosting +@subsection Hosting + +We're looking for people who can host machines and help out whenever +physical access is needed. More specifically: + +@itemize +@item +We need hosting of ``small'' machines such as single-board computers (AArch64, +RISC-V) for use as build machines. + +@item +We need hosting for front-ends and x86_64 build machines in a data center where +they can be racked and where, ideally, several local Guix sysadmins can +physically access them. +@end itemize + +The machines should be accessible over Wireguard VPN most of the +time, so longer power or network interruptions should be the +exception. + +Prerequisites: Familiarity with installing and remotely administering Guix +System. + +@node Administrative Tasks +@subsection Administrative Tasks + +The infra remains up and running thanks to crucial administrative tasks, which +includes: + +@itemize +@item +Selecting and purchasing hardware, for example build machines. +@item +Renewing domain names. + +@item +Securing funding, in particular via the Guix Foundation: +@url{https://foundation.guix.info, Guix Foundation} +@end itemize + +Prerequisites: Familiarity with hardware, and/or DNS registrars, +and/or sponsorship, and/or crowdfunding. base-commit: d108a7aac2c51f21c55cb8ea8801629a97f5242a -- 2.46.0