about summary refs log tree commit diff
path: root/genenetwork/containers/cgit-container.scm
blob: 888136057cc56d3321310dfe1ec2d19bdaf12299 (plain)
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
128
129
130
131
132
133
134
135
136
137
138
139
140
141
142
143
144
145
146
147
148
149
150
151
152
153
154
155
156
157
158
159
160
161
162
163
164
165
166
167
168
169
170
171
172
173
174
175
176
177
178
179
180
181
182
183
184
185
186
187
188
189
190
191
192
193
194
195
196
197
198
199
200
201
202
203
204
205
206
207
208
209
210
211
212
213
214
215
216
217
218
219
220
221
222
223
224
225
226
227
228
229
230
231
232
233
234
235
236
237
238
239
240
241
242
243
244
245
246
247
248
249
250
251
252
253
254
255
256
257
258
259
260
261
262
263
264
265
266
267
268
269
270
271
272
273
274
275
276
277
278
279
280
281
282
283
284
285
286
287
288
289
290
291
292
293
294
295
296
297
298
299
300
301
302
303
304
305
306
307
308
309
310
311
312
313
314
315
316
317
318
319
320
321
322
323
324
325
326
327
328
329
330
331
332
333
334
335
336
337
338
339
340
341
342
343
344
345
346
347
348
349
350
351
352
353
354
355
356
357
358
359
360
361
362
363
364
365
366
367
368
369
370
371
372
373
374
375
376
377
378
379
380
381
382
383
384
385
386
387
388
389
390
391
392
393
394
395
396
397
398
399
400
401
402
403
404
405
406
407
408
409
410
411
412
413
414
415
416
417
418
419
420
421
422
423
424
425
426
427
428
429
430
431
432
433
434
435
436
437
438
439
440
441
442
443
444
445
446
447
448
449
450
451
452
453
454
455
456
457
458
459
460
461
462
463
464
465
466
467
468
469
470
471
472
473
474
475
476
477
478
479
480
481
482
483
484
485
486
487
488
489
490
491
492
493
494
495
496
497
498
499
500
501
502
503
504
505
506
507
508
509
510
511
512
513
514
515
516
517
518
519
520
521
522
523
524
525
526
527
528
529
530
531
532
533
534
535
536
537
538
539
540
541
542
543
544
545
546
547
548
549
550
551
552
553
554
555
556
557
558
559
560
561
562
563
564
565
566
567
568
569
570
571
572
573
574
575
576
577
578
579
580
581
582
583
584
585
586
587
588
589
590
591
592
593
594
595
596
597
598
599
600
601
602
603
604
605
606
607
608
609
610
;;; genenetwork-machines --- Guix configuration for genenetwork machines
;;; Copyright © 2021 Bonface K. M. <bonfacemunyuki@gmail.com>
;;; Copyright © 2024 Pjotr Prins <pjotr.prins@thebird.nl>
;;;
;;; This file is part of genenetwork-machines.
;;;
;;; genenetwork-machines 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.
;;;
;;; genenetwork-machines 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 genenetwork-machines.  If not, see
;;; # cgit container — git access for participants (HOWTO)
;;;
;;; This document describes how participants get git access to the
;;; repositories served by the cgit container
;;; (`genenetwork/containers/cgit-container.scm`), how the container is run,
;;; and which directories to bind-mount so that data survives container
;;; restarts.
;;;
;;; Status of the implementation:
;;;
;;; * already in the container: cgit web UI on port **80** (Anubis
;;;   protected), smart-HTTP **clone/fetch** through git-http-backend
;;;   (anonymous read-only; git-http-backend refuses unauthenticated push
;;;   by default), sshd on port **2224** with pinned host keys and
;;;   password-less root login for the admin key.  The repositories
;;;   themselves live on the host (see the bind-mount section); the
;;;   container does not seed anything.
;;; * by design **not in the container**: any write access.  The `git`
;;;   user, the participants' keys and the repositories live on the *main
;;;   host*; the container only mounts the repository directory read-only.
;;;   Wiring the read-only bind mount is the only remaining step on the
;;;   container side.
;;;
;;; ## Design: the host owns writes, the container reads
;;;
;;; All pushes happen on the main host as the `git` user; the cgit
;;; container is a pure consumer.  This resolves ownership cleanly: the
;;; container needs no `git` account, no group coordination between the
;;; git and nginx users, no port forwarding, and nothing writable — so
;;; repository data cannot be damaged from inside the container.
;;;
;;; On the main host (as root):
;;;
;;; ```sh
;;; # the git user, restricted to git commands only
;;; useradd -m -s "$(command -v git-shell)" git
;;;
;;; # repositories (bare) in the public tree
;;; mkdir -p /home/git/public
;;; sudo -u git git init --bare /home/git/public/demo.git
;;;
;;; # participants' public keys, one line per key
;;; install -d -m 0700 -o git -g git /home/git/.ssh
;;; cat participant-*.pub >> /home/git/.ssh/authorized_keys
;;; chown git:git /home/git/.ssh/authorized_keys && chmod 0600 /home/git/.ssh/authorized_keys
;;; ```
;;;
;;; * everyone authenticates with their own key but logs in as the same
;;;   `git` user — since every participant may write every repo, there is
;;;   nothing to distinguish, and plain SSH needs no gitolite.  Revoking
;;;   someone = removing their line from `authorized_keys`.
;;; * `git-shell` refuses interactive logins and any command outside
;;;   git-upload-pack/git-receive-pack.
;;; * repositories must stay **world-readable** (`chmod -R a+rX
;;;   /home/git/public` once; git's default umask keeps new objects
;;;   readable) — they are public data anyway, and the container's nginx
;;;   user reads them without any group setup.  An optional extra lock is
;;;   the read-only bind mount below: even a compromised container process
;;;   cannot write repository data.
;;;
;;; ### Creating a repository (host, as root)
;;;
;;; ```sh
;;; sudo -u git git init --bare /home/git/public/<name>.git
;;; ```
;;;
;;; No container restart needed — cgit rescans the directory.
;;;
;;; ### Participant workflow
;;;
;;; ```sh
;;; git clone git@git.genenetwork.org:public/<name>.git   # push channel (SSH)
;;; git clone https://git.genenetwork.org/<name>          # anonymous read (HTTPS)
;;; ```
;;;
;;; Pushes are only possible over SSH to the host; over HTTP they are
;;; refused by design (git-http-backend's default for unauthenticated
;;; requests).
;;;
;;; ## Running the container
;;;
;;; The container shares the host network namespace (`--network`), so the
;;; container's ports are plain host ports: web 80, ssh 2224.
;;;
;;; Clone guix-bioinformatics, gn-machines and guix-forge repos in ~/guix/
;;;
;;; Build using a recent version of guix:
;;;
;;; ```sh
;;; guix system container --network \
;;;   --expose /home/git/public \
;;;   -L ~/guix/guix-bioinformatics \
;;;   -L ~/guix/gn-machines \
;;;   -L ~/guix/guix-forge/guix \
;;;   ~/guix/gn-machines/genenetwork/containers/cgit-container.scm
;;; ```
;;;
;;; The three `-L` load paths are all required: `guix-bioinformatics`
;;; provides the `anubis` package, `gn-machines` the `genenetwork services`
;;; module (cgit.scm and the container file), and the guix-forge checkout
;;; provides the forge cgit/anubis service definitions cgit.scm was
;;; derived from.  Building is incremental: an unchanged configuration
;;; returns the existing store item instantly; only changes to the source
;;; files or their inputs trigger a rebuild.  `--network` makes the
;;; container share the host network namespace, so its nginx, sshd and any
;;; other listeners appear as plain host ports — no port forwarding needed.
;;;
;;; This prints a `/gnu/store/…-run-container` script.  Run it under the
;;; run-guix-system-container daemon (which keeps it supervised across
;;; reboots):
;;;
;;; ```sh
;;; ruby $base/run-guix-container/bin/run-guix-container.rb \
;;;   --daemon 127.0.0.1:8900 /gnu/store/…-run-container
;;; ```
;;;
;;; (The client verifies the daemon's fingerprint before every command;
;;; it is generated when the daemon starts and printed by the client.)
;;;
;;; Then:
;;;
;;; ```sh
;;; curl http://127.0.0.1/                         # cgit UI (Anubis challenge)
;;; git ls-remote http://127.0.0.1/demo            # smart HTTP read
;;; ssh -p 2224 -i …/hello-container-key root@127.0.0.1   # admin ssh
;;;    # (the pinned keys ship in gn-machines/etc/)
;;; ```
;;;
;;; Tests: `genenetwork/services/test/run_container_tests.sh` runs the
;;; build + boot + full HTTP test cycle (`cgit_http_tests.py`, 26 checks including the
;;; Anubis tests, plus a tool and ssh check).
;;;
;;; ## Configuration parameters
;;;
;;; Everything is set through Guix service records.  The defaults live in
;;; `cgit.scm`; `cgit-container.scm` overrides what the container needs.
;;;
;;; ### `<cgit-web-configuration>` (cgit.scm)
;;;
;;; | Field | Type / default | Meaning |
;;; |-------|----------------|---------|
;;; | `cgit` | package, `cgit-pink` | the cgit implementation |
;;; | `git` | package, `git-without-safe-directory-check` | git without the `safe.directory` check (the CGI runs unprivileged, repos may be root-owned) |
;;; | `port` | string, `"8883"` | nginx listen port (the public listener, or the Anubis front-end's internal one — see below) |
;;; | `server-name` | string, `"cgit"` | nginx `server_name` |
;;; | `repository-directory` | string, `"/srv/git"` | cgit `scan-path`; also `GIT_PROJECT_ROOT` for git-http-backend |
;;; | `socket` | string, `"/var/run/fcgiwrap/cgit/socket"` | unix socket the fcgiwrap instance serves the cgit and git-http-backend CGIs on |
;;; | `root-title`, `root-desc` | strings | cgit index page header |
;;; | `readme` | list of strings | filenames tried as the repository readme (e.g. `README.md`) |
;;; | `snapshots` | list of strings, `("tar.gz")` | snapshot formats offered per repo |
;;; | `mimetype-file` | file-like or `#f` | mime.types used for raw file serving |
;;; | `repository-sort` | `'age` or `'name` | index page ordering |
;;; | `plain-email?` | boolean, `#f` | render commit author e-mails un-obfuscated |
;;; | `cache-root` | string, `"/var/cache/cgit"` | cgit page cache directory |
;;; | `extra-options` | list of `(KEY . VALUE)` pairs | appended verbatim to the generated cgitrc; `VALUE #f` or omitted means `KEY=1` |
;;; | `fcgiwrap-processes` | integer, `4` | fcgiwrap worker count serving cgit |
;;; | `anubis?` | boolean, `#f` | proxy the tree/diff URIs through the Anubis AI-bot firewall; git smart-HTTP endpoints and static assets stay direct |
;;; | `trusted-proxies` | list of strings, `("127.0.0.1")` | reverse proxies whose client-address header is believed (`set_real_ip_from`); see *Deploying behind a reverse proxy* below.  Set to `'()` when the instance is exposed directly |
;;; | `real-ip-header` | string, `"X-Forwarded-For"` | header the trusted proxies set |
;;; | `internal-listen` | string, `"127.0.0.1:8081"` | address:port of the internal cgit server (`anubis? #t` only), reachable from localhost alone.  Change it when 8081 is taken on the host, since `--network` shares the host network namespace |
;;;
;;; ## Deploying behind a reverse proxy
;;;
;;; PUBLIC deployments terminate TLS on the host and proxy to the
;;; container's listener.  That proxy **must** pass the client address,
;;; otherwise every request arrives from the proxy's own address (in
;;; this container: `127.0.0.1`) and all four rate limiters -- keyed on
;;; `$binary_remote_addr` -- collapse into ONE budget shared by the
;;; whole internet: 5 requests/second, 20 connections, and 60
;;; requests/minute for `/log/`, `/commit/` and `/diff/` for everybody.
;;; That is not hypothetical: it produced a steady stream of
;;; `429 Too Many Requests` for ordinary users (9 of 12 requests
;;; rejected at a rate of one request every two seconds, and
;;; `git clone` failing on its first request).
;;;
;;; The host server block therefore needs:
;;;
;;; ```nginx
;;; server {
;;;     server_name git.genenetwork.org;
;;;     location / {
;;;         proxy_pass         http://127.0.0.1:8011/;
;;;         proxy_redirect     off;
;;;         proxy_set_header   Host              $host;
;;;         proxy_set_header   X-Real-IP         $remote_addr;
;;;         proxy_set_header   X-Forwarded-For   $proxy_add_x_forwarded_for;
;;;     }
;;; }
;;; ```
;;;
;;; The container side is already wired: `cgit-http-directives` emits
;;; `set_real_ip_from 127.0.0.1;`, `real_ip_header X-Forwarded-For;` and
;;; `real_ip_recursive on;` from the `trusted-proxies` /
;;; `real-ip-header` fields, so `$binary_remote_addr` is the real
;;; client again and each client gets its own budget.  Those directives
;;; need the nginx real_ip module, which Guix's stock nginx does NOT
;;; build, so the container uses `nginx-realip' (guix-bioinformatics,
;;; gn/packages/web.scm: stock nginx plus --with-http_realip_module).
;;; Keep `trusted-proxies` as narrow as the deployment allows (a client
;;; that can reach the listener directly could otherwise pick its own
;;; bucket); behind Anubis the internal server trusts the same address,
;;; so the forwarded chain survives the extra hop.
;;;
;;; Also note the host-side user-agent map (`$block_ua` -> `444`): it
;;; closes the connection for the UAs it matches, which is why plain
;;; `curl` sees no response at all while `wget` and `git` get through.
;;;
;;; ### Anonymous reads: clone and /plain/
;;;
;;; Two kinds of anonymous reads must not meet the challenge:
;;;
;;; * **git clone/fetch** -- the smart HTTP endpoints (`info/refs`,
;;;   `git-upload-pack`, `HEAD`, `git-receive-pack`) have their own
;;;   location in the PUBLIC server and talk to `git-http-backend`
;;;   directly, in both modes.  Clones are ordinary HTTP requests, so
;;;   they only get the general per-client rate limit; a clone issues a
;;;   handful, so 5 r/s with burst 30 is ample.
;;; * **`/plain/`** -- raw file content (`curl`, `wget`, `git archive`).
;;;   This one is NOT handled at the nginx layer: it goes through Anubis
;;;   like everything else, and the shared Anubis policy
;;;   (`%anubis-challenge-all-policy` in `(genenetwork services anubis)`)
;;;   ALLOWs curl/wget on `/<repo>/plain/` without the challenge.  The
;;;   rule additionally requires that the request carries no
;;;   `Sec-Fetch-*` header, so a browser (or a headless browser claiming
;;;   a curl user agent) is still challenged and can solve it normally.
;;;
;;;   Keeping this in the policy rather than in a parallel nginx
;;;   location means one gate, one place to change the bot rules, and no
;;;   `if` around `proxy_pass`.  The trade-off: any client can send
;;;   `User-Agent: curl/...`, so /plain/ is reachable by a determined
;;;   scraper -- but with no `Sec-Fetch-*` headers only, and the rate
;;;   limits still apply.
;;;
;;; The host proxy sits in front of all of this, so its UA map must not
;;; kill the agents we allow.  `$block_ua -> 444` currently matches plain
;;; `curl` (which is why curl gets no response at all while `wget` and
;;; `git` pass): exempt the path, or drop `curl` from that map:
;;;
;;; ```nginx
;;; # in the host block, replacing `if ($block_ua) { return 444; }'
;;; map "$block_ua:$uri" $block_this {
;;;     default            $block_ua;
;;;     "~^1:/.*/plain/"   0;   # raw downloads are for curl/wget
;;; }
;;; if ($block_this) { return 444; }
;;; ```
;;;
;;; With `anubis? #t` the public nginx listens on `port` (80) and
;;; proxies Anubis-verified browser traffic to the cgit front-end on
;;; 8081-loopback only; without it, the configured `port` is the public
;;; listener directly.  The git-over-HTTP endpoints (`info/refs`,
;;; `git-upload-pack`, `git-receive-pack`) bypass Anubis in both modes,
;;; so clones keep working.
;;;
;;; The Anubis instance runs the challenge-all policy
;;; (%anubis-challenge-all-policy in cgit.scm): EVERY client reaching
;;; it gets the proof-of-work challenge -- browsers solve it and get
;;; a cookie, curl/wget/feed readers/AI crawlers stay blocked.
;;; Anubis's built-in default policy, by contrast, passes
;;; non-browser user agents through unchallenged.  The git clone
;;; endpoints are unaffected either way (they never reach Anubis);
;;; note that cgit atom feeds and tarball snapshot downloads DO go
;;; through the challenge, so non-browser clients lose access to
;;; those.
;;;
;;; nginx is the stock nginx-service-type instantiated above; the
;;; cgit sites (and the Anubis variant's public/internal server
;;; split) are plain nginx-server-configuration records contributed
;;; by cgit-nginx-service-type -- no hand-rolled conf strings.
;;;
;;; Rate limiting: two layers, both keyed on the client IP
;;; ($binary_remote_addr) so one abusive client cannot spend another's
;;; budget.  The GENERAL layer applies to every request on the public
;;; listener (server-level `limit_req` / `limit_conn`): 5 requests per
;;; second per IP (shared zone `perip`, burst 30 `nodelay`) plus a cap
;;; on concurrent connections per IP (zone `connperip`, 20).  Bots that
;;; keep one connection open are not caught by the connection cap, so
;;; the request rate is the one that matters most for them.
;;;
;;; On top of that, the expensive cgit endpoints (`/diff/`, `/commit/`,
;;; `/log/`) get a stricter limit of 60 requests/minute per client IP
;;; (shared zone `cgit-expensive`, burst 20 `nodelay`) -- one request
;;; per second sustained, which leaves normal browsing (log -> commit ->
;;; diff, a few commits in tabs) alone while still stopping history
;;; walks.  The expensive limit applies in both modes: in the plain
;;; variant it protects the public listener directly, with Anubis it
;;; sits in the internal server and stops crawlers that *pass* the
;;; challenge from hammering history walks.  The general limit sits on
;;; the public listener only -- behind Anubis the internal server sees
;;; every request from 127.0.0.1, so keying a limit there would lump
;;; all clients together.
;;;
;;; "Per client IP" holds only when the client IP is actually visible:
;;; the host proxy in front must send `X-Forwarded-For`, and the
;;; container must believe it (see *Deploying behind a reverse proxy*
;;; above and the `trusted-proxies` field).  Without both, one shared
;;; bucket throttles the whole site.
;;;
;;; Both layers answer 429 Too Many Requests and log at `warn` level
;;; (`limit_req_log_level` / `limit_conn_log_level`) for fail2ban; the
;;; container's nginx runs at `warn` log level so those lines reach
;;; /var/log/nginx/error.log.  Note that the logged address is the
;;; *recovered* client address -- with the proxy misconfigured they all
;;; say 127.0.0.1, and a fail2ban rule would then ban the proxy and take
;;; the site down.
;;;
;;; The directives travel in this container's nginx-configuration
;;; extra-content (`(cgit-http-directives %cgit-web-config)` from
;;; cgit.scm, which emits the real-IP recovery plus the zone
;;; definitions); the knobs are `%cgit-perip-rate` / `%cgit-perip-burst`
;;; / `%cgit-connperip-limit` and `%cgit-expensive-rate` /
;;; `%cgit-expensive-burst` in cgit.scm; the regression tests are t19
;;; to t26 in `genenetwork/services/test/cgit_http_tests.py`.
;;;
;;; Browser note: Anubis sets `Secure` cookies by default, which browsers
;;; drop on plain HTTP.  Behind a TLS-terminating host proxy (the
;;; deployment model) this is correct behaviour.  For HTTP-only testing
;;; keep `anubis? #f` — the current container enables it, so browser
;;; sessions over plain HTTP will hit the "cookies disabled" page until
;;; either TLS terminates at the host or the cookie policy is adjusted.
;;;
;;; ### `<anubis-configuration>` (cgit.scm)
;;;
;;; | Field | Type / default | Meaning |
;;; |-------|----------------|---------|
;;; | `package` | package, `anubis-ai-firewall` | the Anubis implementation |
;;; | `target` | string, `"http://127.0.0.1:8081"` | upstream Anubis proxies to after a successful challenge |
;;; | `policy` | file-like, `%anubis-challenge-all-policy` | Anubis policy document; the default challenges every client (browsers solve the proof-of-work, anything else stays blocked); `#f` selects Anubis's built-in default, which passes non-browser user agents through unchallenged |
;;; | `difficulty` | integer, `4` | proof-of-work difficulty; each increment doubles the work a client must burn per challenge.  Raise to 10-12 when headless browsers start solving their way through |
;;;
;;; Anubis runs on a unix socket (`/var/run/anubis/socket`) and is
;;; instantiated explicitly in the OS when `anubis? #t`; it does not
;;; take part in the extension mechanism (see the notes in cgit.scm for
;;; why).
;;;
;;; ### Container-level knobs (cgit-container.scm)
;;;
;;; | Knob | Where | Meaning |
;;; |------|-------|---------|
;;; | `%cgit-web-config` | top of the file | the one `cgit-web-configuration` shared by the web and nginx services (change `repository-directory`, `anubis?`, titles here) |
;;; | `container-ssh-service` | services list | the shared SSH setup (genenetwork services container-ssh): sshd port 2224, password-less root login with the pinned `~/hello-container-key`, pinned host key in `/etc/ssh`, `/var/empty` fix.  Participant keys live on the **host** `git` account, not here — the container never accepts pushes |
;;; | `packages` | OS field | minimal package set (git, python for the seed/tests, gzip for snapshots) |
;;; | `file-systems` | OS field | **unused for host mappings** — `guix system container` drops custom entries; use `--expose` at build time instead (see the bind-mount section) |
;;; | `cgit-demo-repository-service` | services list | seeds the demo repo; **disable** once the read-only `/srv/git` bind mount is active |
;;; | sysctl/udev no-ops | shepherd services | container-specific workarounds; do not remove (their real counterparts hang container boot) |
;;;
;;; The same `<cgit-web-configuration>` record drives the VM
;;; (`vms/cgit-vm.scm`) — the shared `cgit.scm` services module is
;;; identical for both; only the container/VM wrappers differ.
;;;
;;; ## Keys
;;;
;;; The container pins an SSH host key and ships the admin key for
;;; password-less root login.  Both live **outside the repository**,
;;; directly in the building user's `$HOME` (keys in `$HOME` itself:
;;; `$HOME/ssh-container-key{,.pub}` and `$HOME/hello-container-key{,.pub}`).
;;; Generate them once, by hand, before building:
;;;
;;; ```sh
;;; ssh-keygen -t ecdsa   -f ~/ssh-container-key   -N "" -C "container host key"
;;; ssh-keygen -t ed25519 -f ~/hello-container-key -N "" -C "container admin key"
;;; ```
;;;
;;; * `ssh-container-key`: the pinned SSH *host* key presented by the
;;;   containers (copied into `/etc/ssh` at activation).  Regenerating it
;;;   changes the containers' host identity — update your known_hosts.
;;; * `hello-container-key`: the admin key for password-less root login;
;;;   keep the private half where you ssh from.
;;;
;;; The container definitions fetch the keys from `$HOME` at build time.
;;; Building without them fails with a missing-file error, which is the
;;; reminder to create them.  The private keys never enter the
;;; repository.
;;;
;;; ## Bind mounts (persistence)
;;;
;;; A `guix system container` has a private root: the host filesystem is
;;; not visible inside, and directories outside the read-only store are
;;; recreated empty on restart.  With the host-owns-writes design this
;;; mostly stops mattering — repositories live on the host — but the
;;; container must be given a view of them.
;;;
;;; **Use the `--expose` build option, not OS file-system records.**  A
;;; plain `file-system` entry in the OS is silently dropped by
;;; `guix system container` from the generated run-container script, while
;;; the shepherd inside still creates a mount service for it; that service
;;; then fails (the host path is not visible inside the container) and
;;; wedged boots were observed.  The generated script natively supports
;;; read-only host mappings instead:
;;;
;;; ```sh
;;; guix system container --network \
;;;   --expose=/home/git/public=/home/git/public \
;;;   -L $base/guix-bioinformatics -L $base/gn-machines \
;;;   -L $base/contrib/guix-forge/guix \
;;;   $base/gn-machines/genenetwork/containers/cgit-container.scm
;;; ```
;;;
;;; The same-path mapping keeps `repository-directory /home/git/public`
;;; (the container configuration) valid.  The mount is read-only: even
;;; root inside the container cannot alter repository data.  Verify inside
;;; the container with `grep /home/git/public /proc/mounts` (the entry
;;; must carry `ro`) — reachable via the container's own sshd.
;;;
;;; On the host, before starting the container:
;;;
;;; ```sh
;;; mkdir -p /home/git/public
;;; chmod -R a+rX /home/git/public
;;; ```
;;;
;;; Notes:
;;;
;;; * with the read-only mount active, **do not enable
;;;   `cgit-demo-repository-service`** in `cgit-container.scm`: it seeds
;;;   the repository directory and would fail on the read-only mount.
;;;   Create demo/test repositories on the host instead
;;;   (`sudo -u git git init --bare /home/git/public/<name>.git`).
;;; * the container's nginx reads the repos as its own (container-local)
;;;   user; world-readable host files make that work with zero uid/group
;;;   coordination.
;;; * the VM (`vms/cgit-vm.scm`) does not need this — its qcow2 disk
;;;   persists; container mappings belong in the start command, not the
;;;   shared `cgit.scm` services module.
;;; * after changing the mapping, rebuild the container (the build command
;;;   above) and restart it through the daemon.
;;;
;;; ## Cheat sheet
;;;
;;; | Task                             | Command                                                            |
;;; |----------------------------------|--------------------------------------------------------------------|
;;; | Build the container              | `guix system container --network -L … cgit-container.scm`          |
;;; | Run it supervised                | `run-guix-container.rb --daemon 127.0.0.1:8900 --fingerprint … <run-script>` |
;;; | Web UI                           | `http://<host>/` (Anubis challenge in browsers)                     |
;;; | Anonymous clone (HTTP)           | `git clone http://<host>/<name>` (https via host TLS proxy)        |
;;; | Participant clone/push (host ssh)| `git clone git@<host>:public/<name>.git`                           |
;;; | Admin ssh                        | `ssh -p 2224 -i …/hello-container-key root@<host>`                 |
;;; | Create a repo (host, root)      | `sudo -u git git init --bare /home/git/public/<name>.git`          |
;;; | Add/remove a participant        | edit `/home/git/.ssh/authorized_keys` on the host (live)           |
;;; | Full test cycle                 | `genenetwork/services/test/run_container_tests.sh`                 |

(define-module (genenetwork containers cgit-container)
  #:use-module (gnu)
  #:use-module (genenetwork services cgit)
  #:use-module (genenetwork packages)
  #:use-module (gnu services web)
  #:use-module (genenetwork services container-ssh)
  #:use-module (guix gexp)
  #:use-module (guix build utils)
  #:use-module (gnu services base)
  #:use-module (gnu services shepherd)
  #:use-module (gnu services sysctl)
  #:use-module ((gn packages web) #:select (nginx-realip))
  #:use-module (gnu packages version-control))
(use-package-modules base bash admin compression linux python)

;; The pinned SSH keys live in the building user's $HOME and are
;; fetched from there at build time; container-ssh-service (shared
;; with the other containers) wires them into sshd.  See the Keys
;; Keys section below in this file.

(define %cgit-web-config
  (cgit-web-configuration
   ;; We only serve plain HTTP on port 80 (TLS terminates elsewhere).
   (port "8011")
   (root-title "GeneNetwork cgit")
   (root-desc "Git repositories for the GeneNetwork project")
   (repository-directory "/home/git/public")
   ;; The host proxy (nginx on the deployment host) terminates TLS and
   ;; forwards to 127.0.0.1:8011; trusting loopback for the client
   ;; address is what keeps the rate limits per user instead of per
   ;; proxy.  Set to '() if the container is ever exposed directly.
   (trusted-proxies (list "127.0.0.1"))
   ;; Protect the web UI with the Anubis AI-bot firewall.
   (anubis? #t)))

(operating-system
  (host-name "cgit-container")
  (timezone "Etc/UTC")
  (locale "en_US.utf8")
  (bootloader (bootloader-configuration
               (bootloader grub-bootloader)
               (targets '("/dev/sdX"))))
  (file-systems (cons (file-system
                        (device (file-system-label "does-not-matter"))
                        (mount-point "/")
                        (type "ext4"))
                      %base-file-systems))

  ;; Run PID 1 with the self-pipe signal variant: see
  ;; shepherd-for-containers in (genenetwork packages).  Everything
  ;; else about the system's shepherd is the stock one.
  (essential-services
   (modify-services (operating-system-default-essential-services
                     this-operating-system)
     (shepherd-root-service-type config =>
       (shepherd-configuration
        (inherit config)
        (shepherd shepherd-for-containers)))))

  ;; Minimal package set: nginx and cgit come in through the services,
  ;; ssh tools through the openssh service and 'herd' through the
  ;; essential shepherd service.  git seeds the demo repository, gzip
  ;; would serve cgit snapshots if they are ever enabled.
  (packages (list bash coreutils shadow grep procps git gzip python))

  (services
   (append
    (list
     ;; The stock nginx front-end.  cgit-nginx-service-type below
     ;; contributes its nginx-server-configuration sites to it; the
     ;; http-context extra-content carries the real-IP recovery (so the
     ;; rate limits are per client, not per host proxy) and the
     ;; rate-limiting zones the cgit locations reference.
     (service nginx-service-type
              (nginx-configuration
               ;; The stock nginx is built WITHOUT the real_ip module,
               ;; so set_real_ip_from/real_ip_header are unknown
               ;; directives and nginx refuses to start.  This variant
               ;; only adds --with-http_realip_module; the rate limits
               ;; depend on it (see (cgit-http-directives ...) below).
               (nginx nginx-realip)
               ;; Let the rate-limit rejections logged at warn level
               ;; (limit_req_log_level/limit_conn_log_level) actually
               ;; reach the log: with the default error level they are
               ;; dropped before fail2ban can see them.
               (log-level 'warn)
               (extra-content (cgit-http-directives %cgit-web-config))))
     ;; One shared configuration for the web and nginx services (the
     ;; front-end needs the same record to generate the cgitrc for
     ;; fcgiwrap's CGIT_CONFIG environment).
     (service cgit-web-service-type
              %cgit-web-config)
     (service cgit-nginx-service-type
              %cgit-web-config))

    ;; SSH on port 2224: password-less root login with
    ;; hello-container-key, the pinned ECDSA host key (not generated
    ;; at boot) and the /var/empty fix -- all shared with the other
    ;; containers via container-ssh-service.
    (container-ssh-service #:port-number 2224)

    (list
     ;; NOTE: cgit-demo-repository-service is intentionally NOT listed:
     ;; /srv/git is a read-only bind mount of the host repositories
     ;; (see %repos-source), so nothing may seed into it.  Create the
     ;; demo repository on the host instead
     ;; (sudo -u git git init --bare /home/git/public/demo.git).

     ;; In a container the stock sysctl service (walks /etc/sysctl.d,
     ;; writes /proc/sys) and udev (coldplug on the static /dev the
     ;; container runtime sets up) are useless and their start-up hangs
     ;; the whole boot: urandom-seed requires udev, user-processes
     ;; requires urandom-seed, and ssh-daemon requires user-processes.
     ;; The sysctl no-op is still the right place to lower the
     ;; unprivileged-port floor, though.
     ;;
     ;; Port 80 is privileged, and the container runs in a child user
     ;; namespace (host-uids) while sharing the HOST network namespace
     ;; (--network): its root has full capabilities inside that user
     ;; namespace but no CAP_NET_BIND_SERVICE over the network namespace,
     ;; so nginx cannot bind port 80.  Lowering
     ;; net.ipv4.ip_unprivileged_port_start to 0 lifts the restriction
     ;; (the sysctl is per network namespace -- here the host's, so this
     ;; loosens the host accordingly).  /proc is mounted before PID 1
     ;; (call-with-container mounts it for the PID namespace), so writing
     ;; it this early works.
     (simple-service 'container-sysctl
                     shepherd-root-service-type
                     (list (shepherd-service
                            (provision '(sysctl))
                            (one-shot? #t)
                            (start #~(lambda ()
                                       (false-if-exception
                                        (call-with-output-file
                                            "/proc/sys/net/ipv4/ip_unprivileged_port_start"
                                          (lambda (port)
                                            (display "0" port))))
                                       #t)))))
     (simple-service 'container-udev
                     shepherd-root-service-type
                     (list (shepherd-service
                            (provision '(udev))
                            (one-shot? #t)
                            (start #~(const #t))))))
    (modify-services %base-services
      ;; Drop the guix service: its activation runs 'guix archive
      ;; --generate-key' at every boot, which stalls the container
      ;; boot; a minimal container does not need guix-daemon anyway.
      (delete guix-service-type)
      (delete sysctl-service-type)
      (delete udev-service-type)))))