.gitbay/wiki/Architecture/01-System-Context.org

 1#+title: System context
 2
 3[[file:diagrams/01-context.svg]]
 4
 5* What gitbay is
 6
 7A self-hosted git forge: repositories, issues, merge requests, reviews,
 8CI, releases, wikis, snippets and notifications. One Go binary
 9(=gitbayd=), one SQLite database, and the system =git= binary for all
10repository operations.
11
12The design rule that shapes everything else: *SSH is the API*. Every
13operation is a control command in one registry
14(=internal/control/control.go=). Stock OpenSSH reaches all of them; the
15CLI, the web UI and the JSON API are clients of the same registry and
16do not reimplement logic (=internal/httpd/control.go=,
17=internal/httpd/api.go=).
18
19* Actors
20
21| Actor                 | Reaches gitbay through                        | Authenticates with                  |
22|-----------------------+-----------------------------------------------+-------------------------------------|
23| Anonymous visitor     | HTTPS pages, smart HTTP fetch, git:// if on   | nothing                             |
24| Registered user       | SSH (CLI or stock OpenSSH), HTTPS web, API    | SSH key; web session; API token     |
25| Instance administrator| same as a user, plus host shell               | SSH key with admin account; root    |
26| Deploy key holder     | SSH git transport for one repository          | SSH key bound to that repository    |
27| CI runner             | SSH, =runner= commands and clone              | SSH key with =runner= scope         |
28| iOS app               | JSON API over HTTPS; receives APNs pushes     | API token pasted at sign-in         |
29| Webhook receiver      | receives HTTPS POSTs from gitbay              | verifies HMAC-SHA256 signature      |
30
31* External systems
32
33| System                    | Direction | Purpose                                   | Code                               |
34|---------------------------+-----------+-------------------------------------------+------------------------------------|
35| ACME CA (Let's Encrypt)   | out       | TLS certificates                          | =cmd/gitbayd/main.go=       |
36| SMTP relay                | out       | verification, login links, notifications  | =internal/mail/mail.go=            |
37| Apple Push Notification   | out       | iOS notifications                         | =internal/push/apns.go=            |
38| Webhook endpoints         | out       | event delivery, user-configured           | =internal/webhook/webhook.go=      |
39| Mirror remotes            | out / in  | push and pull mirrors, user-configured    | =internal/mirror/mirror.go=        |
40| Package registries        | out       | dependency update checks (opt-in per repo)| =internal/deps/registry.go=  |
41| Offsite object storage    | out       | restic backups (host timer, not gitbayd)  | documented: Admin wiki             |
42
43gitbayd makes no other outbound connection: no telemetry or update
44check.
45
46* Instance modes that change the attack surface
47
48| Setting                          | Default   | Effect                                                      |
49|----------------------------------+-----------+-------------------------------------------------------------|
50| =web.mode=                       | view_only | =accounts= adds login, settings and every web write route (=routes.go=) |
51| =api.enabled=                    | false     | when false there is no credential-bearing HTTP surface       |
52| =registration.mode=              | closed    | =open= admits unknown SSH keys to =register=; =invite= needs a code |
53| =git_daemon.enabled=             | false     | anonymous =git://= on 9418                                  |
54| =push.enabled=                   | false     | APNs worker and device registration                          |
55| =http.tls=                       | acme      | =files= or =off=; =off= also drops HSTS and the cookie Secure flag |
56| =webhooks.allow_local=           | false     | when false, webhook and mirror URLs may not resolve to private or loopback addresses |
57
58gitbay.org runs with =web.mode = accounts=, the API enabled and
59=registration.mode = open=, all three observable from outside (=/login=,
60=/register=, =/api/v1/read= answering 401).