Forge setup

2 files changed, 226 insertions, 5 deletions

diff --git a/content/forge/_index.md b/content/forge/_index.md
index 5f48846..d8701b6 100644
--- a/content/forge/_index.md
+++ b/content/forge/_index.md
@@ -2,14 +2,172 @@
 title: Forge
 ---
 
-Lindenii Forge is a new software forge.
+**Work in progress.**
 
-* [Lindenii Forge on Lindenii Forge](https://forge.lindenii.runxiyu.org/lindenii/:/repos/forge/)
+Lindenii Forge aims to be an uncomplicated yet featured software forge,
+primarily designed for self-hosting by small organizations and individuals.
 
-* [Lindenii Forge on cgit](https://git.lindenii.runxiyu.org/forge.git/)
+The Lindenii project itself
+[runs an instance](https://forge.lindenii.runxiyu.org/),
+where the
+[official source repository of Lindenii Forge](https://forge.lindenii.runxiyu.org/lindenii/:/repos/forge/)
+is located.
 
+## Organization
 
-<iframe style="border: none; width: 100%; height: 70vh;" src="https://forge.lindenii.runxiyu.org/lindenii/:/repos/forge/">
-</iframe>
+Misc URLs (for hosting stylesheets, scripts, the login page, etc.) are like
+`https://forge.example.org/:/functionality...`.
 
+Contentful URLs are like
+`https://forge.example.org/group_name/subgroup_name.../:/module_type/module_name`.
 
+The available `module_type`s are:
+
+* `repos` for version control
+* `tickets` for ticket trackers
+* `discuss` for discussions
+
+Group and subgroup names may not be `:`.
+
+While this syntax looks a bit odd, it makes it possible to unambiguously
+identify where subgroups end and modules begin, without needing to touch the
+database.
+
+## Protocols and user interfaces
+
+The following should be roughly equivalent in functionality:
+
+* Web interface
+* Custom TLS-based API
+* HTTP GraphQL API
+
+The following shall function where they make sense:
+
+* User-friendly SSH interface
+* Email interface
+
+## Features
+
+### Git repos
+
+* Viewing commits and patches
+* Viewing trees and files
+* Viewing arbitrary hashed objects and refs
+* Viewing tags
+
+### Merge requests
+
+Each version-controlled repo ("main repo") has an area for merge requests
+("MR"s) which may be optionally enabled. A MR is a request to merge 
+changes from one branch ("source branch") into another ("destination branch"),
+in the same repo. The source branch usually, but not always, begins with
+`contrib/`.
+
+* Unsolicited pushes to `contrib/...` automatically open a MR, returning
+  instructions to edit the description and manage the MR further, via the
+  SSH standard error channel.
+* Patches received from email will be automatically converted into MRs.
+* The web interface and APIs (to create MRs from existing branches).
+
+MR branches will be synced to automatically created MR-specific mailing lists.
+These mailing lists should have archives accessible via read-only IMAP.
+The contents of merge requests are presented as what would be produced from
+git-send-email.
+
+It should also be possible for people to perform code reviews via email by
+interwoven a quoted patch with replies, and all these replies should be synced
+to the main MR database, presented via IMAP and the Web interface.
+
+This is probably the most unique feature of Lindenii Forge: while the general
+structure is similar to Forgejo-style pull requests, MRs are automatically
+created based on branch namespaces (similar to Gerrit in some respects) and are
+synced to mailing lists. This allows users to submit MRs via email, or git
+push, or the Web interface, or the API, to support developers with different
+workflows.
+
+### Ticket tracking
+
+Ticket tracking works like todo.sr.ht, though we also intend to support IMAP
+for viewing them and downloading them locally for later use.
+
+Directed acrylic graphs or other dependency mechanisms may be considered in the
+far future.
+
+It should be possible to associate tickets with MRs.
+
+### Discussions
+
+Discussions are basically mailing lists that could also be used from a Web
+interface. IMAP archive should be provided.
+
+Discussions are not designed to handle patchsets. Patchsets should be send to
+the corresponding repo, where they are turned into Lindenii patchsets.
+
+Mailing list messages are expected to be plain text. A subset of markdown shall
+be considered. No full-HTML emails are expected for normal traffic.
+
+### CI
+
+We generally prefer to have linters, deployment pipelines and such run on each
+local developer's machine, for example as a pre-commit hook. However there are
+reasons why CI might be useful.
+
+We plan to integrate a builds.sr.ht-style CI in the future.
+
+### Authentication and authorization
+
+* Anonymous SSH and HTTPS read access is possible for public repos.
+* Git write access is authenticated via SSH public keys.
+* The TLS API will be authenticated with TLS client certificates.
+* The web interface has a dedicated login screen. Logins are remembered with
+  cookies. A dropdown box will be available to select the time the user wishes
+  to remain logged in.
+* Commit validation based on SSH signature validation will be implemented.
+
+### Federated authentication
+
+We probably won't fully support ForgeFed because it's way too bloated. However,
+some type of federated authentication may be considered.
+
+Since Forgejo, SourceHut, and GitHub all publicly serve their users' SSH keys,
+people who submit merge requests by pushing via SSH into the branch namespace
+may link their SSH keys to an identity on an external forge. We will also serve
+users' SSH keys, but it would be opt-in.
+
+OpenID Connect will likely not be supported.
+
+This plan is subject to change.
+
+## License
+
+We are currently using the
+[GNU Affero General Public License version 3](https://www.gnu.org/licenses/agpl-3.0.html).
+
+The forge software serves its own source at `/:/source/`.
+
+## Support and development
+
+* We hang out in [`#chat`](https://webirc.runxiyu.org/kiwiirc/#chat)
+  and [`#lindenii`](https://webirc.runxiyu.org/kiwiirc/#lindenii)
+  on [irc.runxiyu.org](https://irc.runxiyu.org).
+  The latter is bridged to [`#lindenii`](https://web.libera.chat/#lindenii)
+  on [Libera.Chat](https://libera.chat).
+* We currently use
+  [the issue tracker on Codeberg](https://codeberg.org/lindenii/forge/issues/)
+  since our own ticket tracking system is not ready yet.
+  Please submit patches by pushing to `contrib/...` in the official repo.
+* We have several Git repo mirrors on a few places:
+  * [Lindenii Forge itself](https://forge.lindenii.runxiyu.org/lindenii/:/repos/forge/)
+  * [The Lindenii Project's cgit](https://git.lindenii.runxiyu.org/forge.git/)
+  * [SourceHut](https://git.sr.ht/~runxiyu/forge/)
+  * [Codeberg](https://codeberg.org/lindenii/forge/)
+  * [GitHub](https://github.com/runxiyu/forge/)
+
+## Code style
+
+We follow the Lindenii Project's general code style, which has a few important
+deviations from what most people may be used to:
+
+* We used tabs for indentation everywhere (Go, C, HTML, CSS, JS, SQL, etc.)
+* All names are in `snake_case`; exported identifiers in Go use
+  `Capitalized_snake_case`. Type identifiers end with `_t`.
diff --git a/content/forge/setup.md b/content/forge/setup.md
new file mode 100644
index 0000000..4125b98
--- /dev/null
+++ b/content/forge/setup.md
@@ -0,0 +1,63 @@
+---
+title: Setup
+---
+
+## Build dependencies
+
+* Git
+* GNU Make
+* C compiler
+* Recent Go toolchain
+
+## Build and install
+
+Clone the source code and run `make`.
+
+Then run `make install` to install it. By default, it installs to `/usr/local/`.
+
+## Runtime dependencies
+
+* Git
+* PostgreSQL 14 or later
+
+## Configuration
+
+### Adding a system user
+
+Note that this process may vary depending on your OS distribution.
+
+```
+useradd -rmd /var/lib/lindenii/forge/ lindenii-forge
+```
+
+### Allowing the binary to listen to low ports
+
+Since we usually listen on port 22 for SSH, it is necessary to allow the
+Lindenii Forge binary to use low ports.
+
+```
+setcap 'cap_net_bind_service=+ep' /usr/bin/lindenii-forge
+```
+
+### Generating SSH host keys
+
+```
+ssh-keygen -t ed25519 -f /etc/lindenii/forge/ssh_forge_ed25519_key -N ''
+```
+
+### Initializing PostgreSQL
+
+Assuming that you use UNIX-domain socket authentication on a local PostgreSQL
+instance,
+
+```
+su - postgres
+createuser lindenii-forge
+createdb -O lindenii-forge lindenii-forge
+psql -f /usr/share/lindenii/forge/schema.sql -d lindenii-forge
+```
+
+### Editing the configuration file
+
+Copy `/usr/share/doc/lindenii/forge/forge.scfg` to `/etc/lindenii/forge.scfg`
+and edit appropriately.