← back

char/sorcery

static-files based git repo viewer

git clone https://git.t4t.associates/char/sorcery

Charlotte Somshow last commit that touched a file in refbar but keep nav on tip588126d

main
7 folders11 files
languages

files

assets/fonts/
extra/sorcery-ssh/
nix/
src/
tests/
tools/
web/
.gitignore162 B
Cargo.lock76.6 KiB
Cargo.toml1.0 KiB
README.md5.2 KiB
build.rs6.2 KiB
deno.json170 B
deno.lock9.5 KiB
example.ngx.ts527 B
flake.lock1.0 KiB
flake.nix7.8 KiB
sorcery.ngx.ts3.7 KiB

sorcery

tiny read-only git repo viewer

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/sorcery
sorceryd 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 forge
After=network.target

[Service]
Type=simple
User=git
Group=git
RuntimeDirectory=sorcery
CacheDirectory=sorcery
ConfigurationDirectory=sorcery
ExecStart=/usr/local/bin/sorceryd
Restart=on-failure
RestartSec=2
UMask=0027
NoNewPrivileges=true
PrivateTmp=true
ProtectSystem=strict
ProtectHome=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-ssh
nix 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 glisten
deno task build
cargo 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.