Update forge docsHEADmaster

3 files changed, 92 insertions, 0 deletions

diff --git a/content/forge/internals/_index.md b/content/forge/internals/_index.md
new file mode 100644
index 0000000..9d00291
--- /dev/null
+++ b/content/forge/internals/_index.md
@@ -0,0 +1,32 @@
+---
+title: Internals
+---
+
+This section describes some of the internals of the forge.
+
+It is not intended for end users or even system administrators, but only for
+developers.
+
+## Architecture
+
+The **main forge daemon** handles HTTP requests, SSH connections, incoming
+emails, IMAP access, the API, and just about anything that the user might
+want to access. It connects to the PostgreSQL database for most of its data,
+with the exception of Git repositories.
+
+The **git2d** daemon is a separate process that handles all Git operations.
+Currently, the forge daemon automatically deploys and starts this daemon
+when it is started, and connects via UNIX domain sockets.
+Note that git2d is currently incomplete, so the forge daemon uses go-git for
+many operations.
+
+Additionally, the main forge daemon currently launches instances of
+git-receivv-pack and git-upload-pack for Git network operations. This will be
+merged into git2d in the future.
+
+In the future Git operations may be delegated to multiple nodes by using TCP
+instead of UNIX domain sockets and by ensuring all Git operations happen
+through git2d.
+
+In the current architecture, git-receive-pack launches a pre-receive hook,
+[hookc](hookc/).
diff --git a/content/forge/internals/hookc.md b/content/forge/internals/hookc.md
new file mode 100644
index 0000000..3c270fc
--- /dev/null
+++ b/content/forge/internals/hookc.md
@@ -0,0 +1,40 @@
+---
+title: hookc
+---
+
+`hookc` is a helper binary for Git server-side hooks that relays the hook's
+context to a persistent daemon via a UNIX domain socket and communicates back
+any relevant responses.
+
+It is intended to be invoked by `git-receive-pack` for hooks such as
+`pre-receive`, `update`, and `post-receive`.
+
+## Environment variables
+
+- `LINDENII_FORGE_HOOKS_SOCKET_PATH`:
+  Absolute path to the UNIX domain socket on which the daemon is listening.
+- `LINDENII_FORGE_HOOKS_COOKIE`:
+  64-character authentication cookie used to validate the hook client to the
+  daemon.
+
+## Operation
+
+lindenii-forge-hookc collects the following information and sends it to
+the daemon:
+
+- All command-line arguments
+- All `GIT_*` environment variables
+- The raw hook stdin (e.g., old/new ref triplets for pre-receive)
+
+After sending this data, it waits for a one-byte status code from the daemon,
+which becomes `hookc`'s own exit status.
+
+If the daemon sends any output afterward, it is forwarded to standard error and
+will appear as `remote:` output to the user.
+
+## Known issues
+
+- The status byte from the daemon currently must be sent before any
+  stderr output.
+- Currently assumes stdin and stderr are pipes, which is not guaranteed
+  in future versions of Git.
diff --git a/content/forge/setup.md b/content/forge/setup.md
index d2686a1..fa19073 100644
--- a/content/forge/setup.md
+++ b/content/forge/setup.md
@@ -75,6 +75,26 @@ createdb -O lindenii-forge lindenii-forge
 psql -f /usr/share/lindenii/forge/schema.sql -d lindenii-forge
 ```
 
+### Setting up your SMTP daemon
+
+You'll need to do this if you want email integration. We'll assume you've
+already configured your DNS records, rDNS, DKIM, SPF, DMARC, etc.
+
+If you run OpenSMTPD, you'd want something like this in
+`/etc/smtpd/smtpd.conf`:
+
+```
+table forge file:/etc/smtpd/forge
+action "FORGE" lmtp "/var/run/lindenii/forge/lmtp.sock" rcpt-to virtual <forge>
+match from any for domain "forge.lindenii.runxiyu.org" action "FORGE"
+```
+
+And for `/etc/smtpd/forge`:
+
+```
+@ forge
+```
+
 ### Editing the configuration file
 
 Copy `/usr/share/doc/lindenii/forge/forge.scfg` to `/etc/lindenii/forge.scfg`