dcosnet
/
sorcery-go
1
0
Fork 0
Code Issues Pull Requests Packages Projects Releases Wiki Activity
sorcery-go/docs/INSTALL.md

6.6 KiB
Executable File
Raw Permalink Blame History

Installing Sorcery-Go in an existing Source Mage chroot

"Drop the binary in. Cast your first spell. The Coven awakens."

This is the definitive drop-in guide. After following it you will have a working sorcery-go binary living alongside the legacy Bash sorcery, reading the same grimoire, able to cast real spells end-to-end.

Prerequisites

Requirement Why Check
Source Mage chroot We reuse its grimoire ls /var/lib/sorcery/codex/grimoire
Go ≥ 1.21 Build the binary go version
root (sudo) Mount OverlayFS, install to /usr/local/sbin id -u == 0
Linux ≥ 4.15 OverlayFS + cgroup v2 freezer uname -r
bash, tar, gpg Spell sourcing + unpack + PGP which bash tar gpg

Optional but recommended:

  • setcap (from libcap) — for running the binary as non-root with CAP_SYS_ADMIN
  • bpftool — for loading eBPF Tomb Guard programs
  • lxc-freeze or systemctl — for the Warding's quarantine logic

1. Build

cd sorcery-go
make build

This produces ./build/sorcery. The build is CGO-free by default so the binary is portable across glibc/musl hosts.

2. Drop-in install

The one-shot installer:

sudo ./scripts/bootstrap.sh

This will:

  1. Build the binary (if ./build/sorcery doesn't exist).
  2. Install it to /usr/local/sbin/sorcery-go (NOT /usr/sbin/sorcery — the legacy Bash sorcery stays untouched).
  3. Create /var/lib/sorcery-go/{state,tomb,build,log} — separate from /var/lib/sorcery so both tools can coexist.
  4. Apply CAP_SYS_ADMIN, CAP_CHOWN, CAP_DAC_OVERRIDE via setcap.
  5. Initialise the bbolt state DB at /var/lib/sorcery-go/state/state.db.
  6. Walk the existing grimoire at /var/lib/sorcery/codex/grimoire and index every spell into memory (printed count should be in the thousands on a real SMGL install).
  7. Install the systemd unit (or OpenRC init script, autodetected).
  8. Optionally load the eBPF Tomb Guard programs.

Or, equivalently, with make:

sudo make drop-in

3. Verify

# State DB is alive
sorcery-go init

# Grimoire index works
sorcery-go gaze depends wget
# → 📜 Dependency tree for wget (5):
#     binutils
#     glibc
#     linux-headers
#     openssl
#     zlib

# Tomb is empty (nothing cast yet)
sorcery-go tomb list

# Warding is active
sorcery-go ward status

4. Cast your first spell

# Static build of busybox — runs without root if you applied setcap
sudo sorcery-go cast busybox --static --default

What happens:

  1. grimoire.IndexAll walks /var/lib/sorcery/codex/grimoire and finds busybox.

  2. warding.VerifySpell checks for a PGP signature on DETAILS.asc (skipped if absent).

  3. legal.Sentinel.Validate checks the license (GPL-2.0 — allowed under strict_copyleft).

  4. cast.Pipeline.Execute runs:

    • Summon — http.Get downloads the source tarball to /var/spool/sorcery-go/.
    • Verify — sha512 hash is computed in-stream and compared to SOURCE_HASH.
    • Sandbox — sandbox.New mounts an OverlayFS at /var/lib/sorcery-go/build/busybox-<taskID>/.
    • Unpack — tar -xf extracts the source into the merged view.
    • ICE — cast.RunICE parses CONFIGURE for config_query directives and prompts (or uses --default to accept defaults).
    • Build — bash -e BUILD runs inside the sandbox with CLONE_NEWNS | CLONE_NEWUTS.
    • Collect — filepath.Walk of the OverlayFS upper dir produces the manifest.
    • Ingest — every file is sha256-hashed and copied into /var/lib/sorcery-go/tomb/blobs/<ab>/<hash>.
    • Seal — the Sarcophagus epitaph (JSON) is written to tomb/epitaphs/<merkleRoot>.json.
    • Journal — the bbolt Journal bucket records StateInstalled.

  5. sorcery-go gaze install busybox lists every file owned by the Essence.

  6. sorcery-go tomb list shows the new Essence in the Tomb.

5. Launch the Coven Mirror WebUI

sudo sorcery-go web --port 8080

Open http://localhost:8080 in a browser. You'll see:

  • Grimoire tab — every spell in the index, searchable.
  • Tomb tab — every Essence, with its Merkle seal.
  • Pulse tab — Coven node list (just self until you join a cluster).
  • Sanctum tab — Warding status (green when eBPF Tomb Guard is active).
  • Portable Bin tab — static ELF downloads.
  • Compliance tab — license heatmap + SBOM export.

The WebUI's POST /api/v1/cast triggers a real cast pipeline; the /api/v1/stream/{id} WebSocket streams real-time log lines from the EventBus to the browser.

6. Coexistence with legacy Bash sorcery

Both tools can run side-by-side indefinitely:

Concern Bash sorcery Sorcery-Go
Binary /usr/sbin/cast /usr/local/sbin/sorcery-go
State /var/lib/sorcery/ /var/lib/sorcery-go/
Spool /var/spool/sorcery/ /var/spool/sorcery-go/
Grimoire /var/lib/sorcery/codex/grimoire (shared, read-only) same
Spell format Bash scripts same (we source them via bash)

The grimoire is read-only for both tools — neither modifies spell files. You can switch between them freely:

sudo cast wget          # legacy Bash cast
sudo sorcery-go cast wget   # new Go cast

The Go binary's state (Tomb, Tablet, Journal) is completely separate, so a broken Go cast never affects the Bash install and vice versa.

7. Uninstall

sudo make uninstall                # removes /usr/local/sbin/sorcery-go
sudo rm -rf /var/lib/sorcery-go    # removes all Go state (Tomb, Tablet, Journal)
sudo rm -rf /var/spool/sorcery-go  # removes cached source tarballs

The legacy Bash sorcery is untouched.

Troubleshooting

"sandbox: overlay mount failed"

You're not root, or your kernel lacks CONFIG_OVERLAY_FS. The pipeline falls back to a plain-dir mode automatically — builds still work, they're just slightly slower (manifest is collected by diffing before/after).

"summon: hash mismatch"

The SOURCE_HASH in the spell's DETAILS doesn't match what's currently being served at the SOURCE_URL. Upstream may have re-rolled the tarball. Re-compute the hash with sha512sum wget-1.21.4.tar.gz and update DETAILS.

"pgp: no GOODSIG in gpg output"

The DETAILS file is signed but the signing key isn't in your keyring. Either import the key (gpg --import <key>) or unset SORCERY_GO_PGP_KEYRING to disable PGP attestation.

"legal: license X is blacklisted"

Your active posture blocks the spell's license. Switch posture:

sudo SORCERY_GO_POSTURE=lawless sorcery-go cast <spell>

Or persist the change in /etc/sorcery-go/env.