A small, read-only web viewer for git repositories, in the spirit of cgit, with a sourcehut-style look. One Go binary with its templates and CSS embedded. Pages need no JavaScript.
It is meant for a personal git server: you push over SSH, and everyone else can browse and clone over HTTPS. It is not a forge: there are no accounts, issues or pull requests.
- Browse: an index of every repository (grouped by folder), summaries
with the README and the license, trees with syntax highlighting, rendered markdown, raw
files, blame, history with a commit graph, commits with diffs and
.diffand.patchdownloads, comparisons between any two refs, refs with how far each branch is from the default one, tags with their release notes, and tarballs and zips. Links can select lines of a file. - Clone anything over HTTPS (
git clone https://git.example.com/NAME). Pushing over HTTP is never possible. - Push over SSH to a locked-down
gitaccount. Pushing to a name that doesn't exist yet creates the repository. - Deploy with one command from your own machine:
./install.sh root@your-serversets up canopy, HTTPS, bot protection, pushing and a hardened server, and can put SSH on a private Tailscale network so that only the web site is public.
| File | What's in it |
|---|---|
| usage.md | Day to day: cloning, pushing, pulling, new repositories, a short SSH name for the server |
| deploy.md | Putting it on a server, from a fresh VPS to a hardened setup with backups |
| security.md | How the server is protected, layer by layer |
| config/README.md | Every setting in config/canopy.toml |
| customisation.md | Themes, your own colours and fonts, step by step |
| development.md | Running and testing it on your own machine, including Windows |
go run ./demo # sample repositories in demo/repos
go run . -config demo/canopy.toml # http://127.0.0.1:8080
Both work on Linux, macOS and Windows; the demo needs only Go and git.
The demo has a C project with releases, merges and branches, a
.dotfiles repository with symlinks, markdown notes with images, a nested
repository, an empty one, and one hidden by the config.
To serve your own folder of repositories:
go build
./canopy -root ~/src -listen 127.0.0.1:8080
From the canopy folder on your machine (needs Go and SSH access to the server):
./install.sh root@git.example.com
It asks a few questions; the defaults are the most secure choices. It then builds canopy for the server, uploads it and installs:
internet --> Caddy :443 (HTTPS) --> Anubis (bot check) --> canopy 127.0.0.1:8080
you --> SSH (over Tailscale) --> git account (git-shell) --> /srv/git
Before finishing it checks that a fresh SSH login and pushing still work,
and undoes the SSH changes if they don't. Later, ./install.sh … --yes
re-deploys with the same answers. deploy.md walks through
the whole thing, including running the installer on the server by hand.
Tested on Debian 13, Ubuntu 24.04 and 26.04, and Fedora 44.
| No hardening | --harden |
--harden --tailscale |
|
|---|---|---|---|
Web site and git clone over HTTPS (80, 443) |
Internet | Internet | Internet |
| Push over HTTP | Never | Never | Never |
Push over SSH (git account) |
Internet, push keys only | Internet, push keys only | Tailnet only, push keys only |
| Admin SSH logins | Internet, the system's own sshd settings | Internet, keys only, listed accounts only | Tailnet only, keys only, listed accounts only |
| Root over SSH | The system's own setting | Never with a password; never at all with an admin account | Same, and tailnet only |
| Other ports | The firewall is left as it is | Blocked | Blocked from the internet |
| canopy and Anubis | This machine only | This machine only | This machine only |
security.md explains each of these.
Everything is in config/canopy.toml:
listen,root(the folder of repositories),depth,title,description,about(a markdown page for an about tab),faviconowner: who the top-level repositories belong to, andowner_url: their website, linked from the footer ("served by you")[clone] http: the base URL shown in clone commands[activity]: an activity tab with a year of commits as a GitHub-style graph (off unlessenabled = true; mirrors never count)[signatures]: SSH keys whose signed commits and tags get a verified badge (off unless a key is listed)[theme]: a colour theme for light and dark mode (GitHub, Ayu, Night Owl / Light Owl, Catppuccin, or your own under[themes]), and Google Fonts for text and code (downloaded and served by canopy, so visitors never contact Google)[repos."name"]: a repository'sdescription,homepage, orhidden = true(or, without touching the config,ssh git@HOST private NAME on)
./canopy -check validates the file and prints the resulting settings.
Unknown keys are errors, so typos don't go unnoticed.
config/README.md describes every setting.
Repositories are found under root, up to depth folders deep: bare
repositories (foo.git) and work trees (foo/.git). The folder path is the
URL, so /srv/git/tools/foo.git is served at /tools/foo and listed under
tools on the index. A repository's description file is its
description. Dot-named folders are only served when they are bare
repositories (.dotfiles.git), so a version-controlled ~/.ssh never is.
Modelled on sourcehut. The item separator lets branch names contain
slashes.
/activity?year={year}&page={n} commit graph and activity, last year by default ([activity] in the config)
/about the about page (about in the config)
/{repo} summary: recent commits, license, refs, clone URL, README
/{repo}/tree/{ref}/item/{path} folder listing or highlighted file
/{repo}/blob/{ref}/item/{path} raw file
/{repo}/blame/{ref}/item/{path} blame
/{repo}/log/{ref}/item/{path} history, paginated, with a commit graph for the whole repository
/{repo}/commit/{hash} commit with diff (.diff for a plain diff, .patch for a mailbox patch)
/{repo}/compare/{from}...{to} the commits {to} has that {from} lacks, and their changes (.diff, .patch)
/{repo}/compare a form for picking two refs to compare
/{repo}/refs branches, each with how far it is from the default branch, and tags (paginated)
/{repo}/tag/{name} a tag: its message (release notes), signature, commit, archives and the changes since the tag before
/{repo}/log.atom Atom feed of the newest commits
/{repo}/tags.atom Atom feed of the newest tags
/{repo}/archive/{ref}.tar.gz tarball (.zip for a zip)
On tree and blame pages, ?lines=12 or ?lines=12-20 highlights lines;
clicking a line number selects it, and clicking another extends the
selection to there.
Pages carry an ETag, so a browser or feed reader asking again gets a short "not modified" until something is pushed. Raw files, diffs, patches and archives stay cached until what they hold changes.
How far each branch is from the default one ("2 ahead, 5 behind main") needs git 2.41 or later on the server; with an older git the refs page leaves the counts out.
git clone https://host/{repo} uses git's smart HTTP protocol, fetch only.
main.go flags, -check, HTTP server
internal/config TOML loading (unknown keys are errors)
internal/fonts downloads [theme] fonts from Google Fonts and caches them
internal/theme built-in colour themes and highlighting styles, [themes] checks
internal/git runs the git binary: log, tree, blob, diff, blame, refs, archive
internal/render syntax highlighting, markdown rendering and sanitizing
internal/sigcheck checks SSH signatures on commits and tags, for [signatures]
internal/server routing, handlers, templates and CSS (embedded)
config/ your settings, about page and icon
demo/ sample repositories and their config
install.sh installer and remote deploy (also writes canopy-update)
update.sh quick redeploy of canopy and config/ only (or CANOPY_CONFIG_DIR)
Development: go test ./..., go vet ./..., gofmt -l .,
shellcheck install.sh update.sh and govulncheck ./... must all be
clean. See development.md for running and testing it
locally.
Copyright (C) 2026 The spinney authors
canopy is free software: you can redistribute it and/or modify it under the terms of the GNU General Public License as published by the Free Software Foundation, either version 3 of the License, or (at your option) any later version. See LICENSE.