From 3bb3b4c65ed516561842b54bf9520dc521a121ff Mon Sep 17 00:00:00 2001 From: Sarah Jamie Lewis Date: Sat, 15 Feb 2025 13:58:22 -0800 Subject: [PATCH 1/1] Update ReadME --- README.md | 42 +++++++++++++++++++++++++++++++++++++++++- 1 file changed, 41 insertions(+), 1 deletion(-) diff --git a/README.md b/README.md index a5399ae..e582914 100644 --- a/README.md +++ b/README.md @@ -1 +1,41 @@ -# Senary - lightweight, mostly static software forge \ No newline at end of file +# Senary - lightweight, mostly static software forge + + +## Configuration + +The directory you run senary from should a copy of the `templates` directory in this repository, and also a `senary.json` file like below: + +``` +{ + "BaseDir":"./static/", + "RepoDir":"./repos/", + "RequestsDir":"./requests", + "CallbackURI": "https://example.com/callback", + "ClientID": "https://example.com/", + "MaintainerDomains": [""], + + "RepoBases": ["./clonedrepos"] +} +```` + +An explanation of each field follows: + +* `BaseDir` - a path to a copy of the `static` directory for this repository +* `RepoDir` - a path to a folder where static caches of each repo will be saved +* `RequestsDir` - a path to a folder where issues and pull requests will be saved +* `RepoBases` - a list of directories where locally cloned repositories can be found. + +### IndieAuth Support + +* `ClientID` - the domain you will be hosting senary on. Note that per the IndieAuth spec, the final slash ('/') is important. +* `CallbackURI` - the url that IndieAuth authorization servers will use to callback to the app, usually `/callback` +* `MaintainerDomains` - a list of domains for which authenticated users will be considered to have maintainer priviledges (the ability to moderate requests, and apply patches) **Security Note: Any authorization server listed here effectively has the ability to update code in repositories, and as such you should limit this list to authorization servers under your control** + +## Repository Configuration + +Senary has the ability to front https git clone requests, if the server is properly configured for them. To do so: + +1. Set up a [bare repo](https://git-scm.com/book/en/v2/Git-on-the-Server-Getting-Git-on-a-Server) for each repository you want to expose. +2. Ensure that each bare repo has `receivepack = false` under its `[http]` config. This will ensure that users cannot push to your repository. (Senary has additional gating which ensures that the receivepack url is not exposed, this is defense-in-depth) +3. For each bare repo, create a clone in one of the directories list in `RepoBases`, this can be done locally `git clone ` +4. Run `./senary build`, this should result in a static html copy of repo resources being created in `/reponame/` \ No newline at end of file -- 2.43.0