char/sorcery
static-files based git repo viewer
git clone https://git.t4t.associates/char/sorcery
588126d
main
languages
- Rust 56.7%
- TypeScript 31.1%
- CSS 4.9%
- Zig 3.9%
- Nix 1.8%
- Markdown 1.2%
- TOML 0.3%
- FJSON 0.2%
files
| assets/fonts/ | |
| extra/sorcery-ssh/ | |
| nix/ | |
| src/ | |
| tests/ | |
| tools/ | |
| web/ | |
| .gitignore | 162 B |
| Cargo.lock | 76.6 KiB |
| Cargo.toml | 1.0 KiB |
| README.md | 5.2 KiB |
| build.rs | 6.2 KiB |
| deno.json | 170 B |
| deno.lock | 9.5 KiB |
| example.ngx.ts | 527 B |
| flake.lock | 1.0 KiB |
| flake.nix | 7.8 KiB |
| sorcery.ngx.ts | 3.7 KiB |
sorcery
tiny read-only git repo viewer
- point at a dir containing
user/repobare git repos - generates static sites for every repo
- serves via nginx (or other proxy supporting the
X-Accelheaders), or directly over HTTP - progressively enhances via js to provide dynamic content (commit diffs, tree-at-revision, etc)
- syntax highlighting via glisten (both serverside and clientside)
- supports "git smart HTTP" for read-only clones
pairs well with ssh git for read-write access
usage
compiles to a static executable (linux musl) on the default package in the flake:
nix build
install it as /usr/local/bin/sorceryd or whatever
build the static cache without starting a server:
sorceryd build --cache /var/cache/sorcerysorceryd build --cache /var/cache/sorcery alice/repo --force
for a standalone local preview without nginx:
sorceryd serve --listen 127.0.0.1:8080 --cache /var/cache/sorcery
both commands read /etc/sorcery/config.toml by default; use --config to choose another file. --cache can be omitted when cache is set in the config or CACHE_DIRECTORY is set by systemd.
custom css
you can edit <cache>/css/theme.css to override the default :root palette
without rebuilding or restarting (edits are preserved across upgrades and GC):
: root { --bg-col : #17131c ; --fg-col : #f5edf9 ; --accent-col : #dca8ff ; }
nginx
production nginx config generated via @char/ngx:
deno run example.ngx.ts> sorcery.conf
or you can use it as a module:
import ngx from "jsr:@char/ngx@0.2" ; import { sorcery } from "./sorcery.ngx.ts" ; export const config = ngx ( undefined , [ ngx ( "upstream sorceryd" , [ "server unix:/run/sorcery/sock" ]) , ngx ( "server" , [ ngx . serverName ( "git.example.org" ) , ... ngx . listen () , ... ngx . letsEncrypt ( "git.example.org" ) , sorcery ({ proxyPass : "http://sorceryd" , cache : "/var/cache/sorcery" , repositories : "/home/git/public" , }) , ]) , ]) ;
for daemonless static serving, omit proxyPass from sorcery(...) and run
sorceryd build whenever repositories change. the browser reads Git objects
from the repositories directly; smart HTTP and on-demand refresh require the
daemon. for dumb HTTP clones at /<user>/<repo>/.git, maintain Git's
info/refs and objects/info/packs with git update-server-info.
systemd
example /etc/systemd/system/sorceryd.service:
[ Unit ] Description = Sorcery Git forgeAfter = network.target[ Service ] Type = simpleUser = gitGroup = gitRuntimeDirectory = sorceryCacheDirectory = sorceryConfigurationDirectory = sorceryExecStart = /usr/local/bin/sorcerydRestart = on-failureRestartSec = 2UMask = 0027NoNewPrivileges = truePrivateTmp = trueProtectSystem = strictProtectHome = read-only[ Install ] WantedBy = multi-user.target
with /etc/sorcery/config.toml:
repositories = "/home/git/public" clone_url_base = "https://my-cool-git.example"
systemd supplies /etc/sorcery/config.toml, /var/cache/sorcery, /run/sorcery/sock, and /run/sorcery/control through the directory settings above. the instance name defaults to the host in clone_url_base.
UMask=0027 restricts /run/sorcery/sock and /var/cache/sorcery to the git group (while /run/sorcery/control stays 0600), so nginx needs to be in the git group and /home/git and /home/git/public need group traverse/read permissions.
command-line flags override SORCERY_* environment variables, which override the config file and systemd defaults.
ssh
sorcery-ssh is an sshd ForceCommand that provides read-write git access.
it auto-creates bare repositories on first push (like sourcehut)
and also provides commands + an optional interactive tui for editing the description of a repo.
nix build .#sorcery-sshnix build .#sorcery-ssh-tui# optional
install sorcery-ssh (and sorcery-ssh-tui) and add the following to sshd_config:
Match User git SetEnv SORCERY_CONTROL_SOCKET=/run/sorcery/control SORCERY_INSTANCE_NAME=my-cool-git.example SORCERY_SSH_TUI=/usr/local/bin/sorcery-ssh-tui SORCERY_REPOSITORIES=/home/git/public SORCERY_CLONE_URL_BASE=https://my-cool-git.example ForceCommand /usr/local/bin/sorcery-ssh
optional: push refresh
since this is a static-files-based viewer, repositories need updating when their state changes.
sorceryd's scanner will pick up changes every SORCERY_CHECK_INTERVAL and auto-rebuild repo sites.
additionally, if you want refresh to happen as soon as possible you can use sorcery-ssh or set a post-receive hook like this:
#!/usr/bin/env sh printf '%s\n' " $PWD " | nc -U /run/sorcery/control
in any case, sorceryd's scanner will pick changes up eventually, so this is optional
development
deno task glisten fetches the GitHub revision of glisten-deno pinned in flake.lock,
builds its grammars, and stages the package in .glisten.
this needs git, WABT, and Binaryen on PATH; nix develop provides them.
no sibling checkout or avril installation is needed.
deno task glistendeno task buildcargo test
since we embed the frontend and grammars inside the executable, you must generate both before running a cargo build. nix build handles this automatically.