Report update progress and log to Hammerhead while updating

Co-Authored-By: Claude Sonnet 5.5 <noreply@anthropic.com>

.dockerignore

@@ -0,0 +1,3 @@
+# The image only packages the binaries that deploy/build.sh already built.
+*
+!dist/bin

.env.example

@@ -13,6 +13,12 @@ BLACKTIP_TOKEN=
 # Serve http/https with Traefik (path to a Traefik v3 binary), and optionally
 # use DNS challenge for wildcard certificates. The provider's credentials go here
 # too, named exactly as Traefik documents for that provider.
-#BLACKTIP_TRAEFIK=/usr/local/bin/traefik
+# Releases bundle a tested Traefik: /usr/local/lib/blacktip/traefik (systemd install),
+# /traefik (Docker image, already set; set it empty to use the built-in proxy).
+#BLACKTIP_TRAEFIK=/usr/local/lib/blacktip/traefik
 #BLACKTIP_ACME_DNS=cloudflare
 #CF_DNS_API_TOKEN=
+
+# Check for new releases every few hours and update and restart by itself (Linux and macOS).
+# setup.sh turns this on; remove it to update by hand.
+#BLACKTIP_AUTO_UPDATE=1

.gitea/workflows/ci.yml

@@ -0,0 +1,50 @@
+name: CI
+
+on:
+  push:
+    branches: [main]
+  pull_request:
+
+jobs:
+  test:
+    runs-on: ubuntu-latest
+    env:
+      GOPRIVATE: git.veillax.com
+    steps:
+      - uses: actions/checkout@v4
+
+      - uses: actions/setup-go@v5
+        with:
+          go-version-file: go.mod
+
+      # Go fetches the other sharks modules straight from this server. This is harmless
+      # for public repositories and is what makes private ones work.
+      - name: Let Go fetch modules from this server
+        run: git config --global url."https://x-access-token:${{ secrets.GITHUB_TOKEN }}@git.veillax.com/".insteadOf "https://git.veillax.com/"
+
+      - name: Formatting
+        run: |
+          unformatted=$(gofmt -l .)
+          if [ -n "$unformatted" ]; then
+            echo "These files need gofmt:"
+            echo "$unformatted"
+            exit 1
+          fi
+
+      - name: Shell scripts parse
+        run: |
+          for f in deploy/*.sh; do sh -n "$f"; done
+
+      - name: Vet
+        run: go vet ./...
+
+      - name: Test
+        run: go test ./...
+
+      # Catches platform-specific breakage before a release is tagged.
+      - name: Every release platform compiles
+        run: |
+          for t in linux/amd64 windows/amd64; do
+            echo "building for $t"
+            GOOS=${t%/*} GOARCH=${t#*/} GOARM=7 CGO_ENABLED=0 go build -o /dev/null ./cmd/blacktip
+          done

.gitea/workflows/release.yml

@@ -0,0 +1,62 @@
+name: Release
+
+# Push a tag such as v0.2.0 to build and publish a release:
+#   git tag -a v0.2.0 -m "blacktip v0.2.0" && git push origin v0.2.0
+on:
+  push:
+    tags: ['v*']
+
+jobs:
+  release:
+    runs-on: ubuntu-latest
+    env:
+      GOPRIVATE: git.veillax.com
+    steps:
+      - uses: actions/checkout@v4
+        with:
+          fetch-depth: 0 # release notes come from the history since the previous tag
+
+      - uses: actions/setup-go@v5
+        with:
+          go-version-file: go.mod
+
+      - name: Let Go fetch modules from this server
+        run: git config --global url."https://x-access-token:${{ secrets.GITHUB_TOKEN }}@git.veillax.com/".insteadOf "https://git.veillax.com/"
+
+      - name: Test
+        run: |
+          go vet ./...
+          go test ./...
+
+      - name: Build release archives
+        run: sh deploy/build.sh "${GITHUB_REF_NAME}"
+
+      # Optional secret RELEASE_TOKEN: an access token that can write releases, for
+      # servers where the automatic job token can't.
+      - name: Publish the release
+        env:
+          TOKEN: ${{ secrets.RELEASE_TOKEN || secrets.GITHUB_TOKEN }}
+        run: sh deploy/publish-release.sh "${GITHUB_REF_NAME}"
+
+      # Skipped when the repository variable PUBLISH_DOCKER is "false", or fails alone
+      # if this runner has no Docker: the release above is already published by then.
+      # Optional secret REGISTRY_TOKEN (and variable REGISTRY_USER): an access token
+      # with package write permission, for servers where the job token can't push.
+      - name: Build and push the container image
+        if: ${{ vars.PUBLISH_DOCKER != 'false' }}
+        env:
+          REGISTRY_TOKEN: ${{ secrets.REGISTRY_TOKEN || secrets.GITHUB_TOKEN }}
+          REGISTRY_USER: ${{ vars.REGISTRY_USER || github.actor }}
+        run: |
+          host=${GITHUB_SERVER_URL#*://}
+          owner=$(echo "$GITHUB_REPOSITORY_OWNER" | tr 'A-Z' 'a-z')
+          image="$host/$owner/blacktip"
+          echo "$REGISTRY_TOKEN" | docker login "$host" -u "$REGISTRY_USER" --password-stdin
+          # a container-driver builder can build several architectures in one go
+          docker buildx create --name release --driver docker-container --use >/dev/null 2>&1 || docker buildx use release
+          tags="-t $image:$GITHUB_REF_NAME"
+          case "$GITHUB_REF_NAME" in
+            *-*) ;;                       # pre-releases (v1.0.0-rc1) don't move :latest
+            *) tags="$tags -t $image:latest" ;;
+          esac
+          docker buildx build --platform linux/amd64 $tags --push .

.gitignore

@@ -3,3 +3,4 @@ bin/
 .env
 wg.key
 *.db
+dist/

Dockerfile

@@ -0,0 +1,26 @@
+# syntax=docker/dockerfile:1
+# Packages the binaries deploy/build.sh already built (dist/bin/linux_<arch>/blacktip),
+# so the arm64 image needs no emulation. Build it with:  sh deploy/build.sh && docker buildx build .
+#
+# Blacktip opens ports on the machine's own IP addresses, so run it with host
+# networking (see deploy/docker-compose.yml). It runs as root in the container so it
+# can bind ports below 1024 such as 80 and 443.
+FROM --platform=$BUILDPLATFORM alpine:3.22 AS prep
+RUN apk add --no-cache ca-certificates \
+ && mkdir /data
+
+FROM scratch
+ARG TARGETARCH
+LABEL org.opencontainers.image.title="Blacktip" \
+      org.opencontainers.image.description="Edge: public ports, WireGuard tunnels, logins and mail egress" \
+      org.opencontainers.image.source="https://git.veillax.com/Veillax/blacktip" \
+      org.opencontainers.image.licenses="AGPL-3.0-only"
+COPY --from=prep /etc/ssl/certs/ca-certificates.crt /etc/ssl/certs/ca-certificates.crt
+COPY --from=prep /data /data
+COPY dist/bin/linux_${TARGETARCH}/blacktip /blacktip
+COPY dist/bin/linux_${TARGETARCH}/traefik /traefik
+# Traefik serves http/https; set BLACKTIP_TRAEFIK= (empty) in .env to use the built-in proxy instead
+ENV BLACKTIP_DATA=/data BLACKTIP_TRAEFIK=/traefik
+VOLUME ["/data"]
+EXPOSE 51820/udp
+ENTRYPOINT ["/blacktip"]

README.md

@@ -21,7 +21,7 @@ Open the WireGuard UDP port (default 51820) and any ports you open from the dash
 | `-tunnel` | `BLACKTIP_TUNNEL` | UDP listen address for WireGuard (default `:51820`) |
 | `-data` | `BLACKTIP_DATA` | folder for the WireGuard key and certificates |
 | `-docker` | `BLACKTIP_DOCKER=1` | report local Docker containers so they can be picked as targets |
-| `-traefik` | `BLACKTIP_TRAEFIK` | path to a Traefik v3 binary, to serve http/https with Traefik |
+| `-traefik` | `BLACKTIP_TRAEFIK` | path to a Traefik v3 binary, to serve http/https with Traefik. Release archives and the Docker image include a tested one |
 | `-acme-dns` | `BLACKTIP_ACME_DNS` | with Traefik: DNS-challenge provider for wildcard certificates |
 | `-no-acme` | | with Traefik: serve its self-signed certificate instead of Let's Encrypt |
 | `-env` | | `.env` file to read (default `./.env`) |
@@ -36,6 +36,44 @@ Settings and secrets can live in a `.env` file instead of the command line; see
 - **Mail egress:** delivers your mail server's outgoing mail straight to the recipient's server from a public IP you choose, with the HELO name you set, opportunistic STARTTLS, optional DKIM signing, MTA-STS enforcement, a per-minute send limit and a deliverability checklist.
 - **Tunnel:** WireGuard through a userspace network stack, so no root, no kernel interface and no driver. It works on Windows, macOS and Linux, and sites behind NAT connect out to it.
 
+## Deploying
+
+Releases are built by Gitea Actions. Pushing a tag such as `v0.2.0` runs `.gitea/workflows/release.yml`, which tests the code, builds Blacktip for Linux (amd64) and Windows (amd64), publishes the archives with a `SHA256SUMS` file on the Releases page, and pushes a container image (linux/amd64) to this server's registry (`git.veillax.com/veillax/blacktip`). Every push and pull request runs `.gitea/workflows/ci.yml`: formatting, vet, tests, and a check that every release platform still compiles.
+
+**On a Linux server (systemd)**
+
+```
+curl -LO https://git.veillax.com/Veillax/blacktip/releases/download/v0.1.0/blacktip_v0.1.0_linux_amd64.tar.gz
+curl -LO https://git.veillax.com/Veillax/blacktip/releases/download/v0.1.0/SHA256SUMS
+sha256sum -c --ignore-missing SHA256SUMS
+tar xzf blacktip_v0.1.0_linux_amd64.tar.gz && cd blacktip_v0.1.0_linux_amd64
+sudo ./install.sh                 # installs the binary and a hardened systemd service
+sudoedit /etc/blacktip/blacktip.env   # your settings and secrets
+sudo systemctl start blacktip
+```
+
+Releases are published for x86-64 only; for ARM machines build it yourself (`TARGETS=linux/arm64 sh deploy/build.sh`). To upgrade, repeat the same steps: your settings and data are kept. `sudo ./install.sh --uninstall` removes the service and binary but leaves `/etc/blacktip` and `/var/lib/blacktip` alone. `blacktip -version` tells you which build is running.
+
+**Updates**
+
+Set `BLACKTIP_AUTO_UPDATE=1` (or pass `-auto-update`) and Blacktip checks this server for a newer release every few hours, verifies it against `SHA256SUMS`, checks that the new binary runs, swaps it in and restarts itself. It only follows full releases (never pre-releases), never downgrades, and keeps the old binary if anything looks wrong. `setup.sh` turns it on. It is not available on Windows, and it is for the systemd and plain-binary installs: with Docker, pull a new image instead.
+
+**With Docker**
+
+```
+cp .env.example .env              # fill it in
+docker compose -f deploy/docker-compose.yml up -d
+```
+
+The image is `git.veillax.com/veillax/blacktip:<version>` (and `:latest` for full releases). The compose file is in the repository and inside each Linux archive.
+
+**Setting up the build (once)**
+
+- A Gitea Actions runner with the label `ubuntu-latest`, and Docker on it if you want the container image.
+- Nothing else is required: the workflows use the automatic job token. If your server doesn't let that token publish releases or packages, add the secrets `RELEASE_TOKEN` and `REGISTRY_TOKEN` (access tokens with release and package write permission) and optionally the variable `REGISTRY_USER`.
+- To skip the container image, set the repository variable `PUBLISH_DOCKER` to `false`.
+- Build locally with `sh deploy/build.sh` (archives in `dist/`).
+
 ## Build and test
 
 ```

blacktip.go

@@ -38,6 +38,13 @@ type Config struct {
 	DataDir    string
 	Docker     bool // report local Docker containers for discovery
 
+	// Version is the release this binary was built from, reported to Hammerhead. AutoUpdate says
+	// whether the program may update itself; only then does it act on an update request from
+	// Hammerhead, by calling UpdateNow (which normally restarts the process into the new binary).
+	Version    string
+	AutoUpdate bool
+	UpdateNow  func(ctx context.Context, progress func(stage string, pct int, line string)) (newVersion string, err error)
+
 	// Traefik, when its Path is set, serves http/https resources instead of the built-in proxy.
 	Traefik TraefikConfig
 
@@ -106,6 +113,13 @@ type Blacktip struct {
 
 	logq       chan model.LogEntry
 	reportMu   sync.Mutex
+	updating   atomic.Bool
+	updateMsg  string // outcome of the update Hammerhead asked for, reported back
+	updateID   string // the request that updateMsg answers
+	updStage   string // progress of the running update, reported to Hammerhead
+	updPct     int
+	updLog     []string
+	updSent    time.Time
 	dockerMu   sync.Mutex
 	dockerAt   time.Time
 	dockerList []model.Container
@@ -252,6 +266,9 @@ func (b *Blacktip) apply(cfg *model.EdgeConfig) {
 	if b.dashboard == "" {
 		b.dashboard = b.cfg.Hammerhead
 	}
+	if cfg.UpdateID != "" {
+		b.requestUpdate(cfg.UpdateID)
+	}
 	b.local = map[string]bool{}
 	for _, id := range cfg.Local {
 		b.local[id] = true
@@ -517,8 +534,11 @@ func (b *Blacktip) report() {
 		IPs: localIPs(), PublicKey: b.wgPub,
 		Status: map[string]model.MappingStatus{}, Stats: map[string]model.Stat{},
 		Containers: b.containers(), MailChecks: map[string]model.MailCheck{},
+		Version: b.cfg.Version, AutoUpdate: b.cfg.AutoUpdate,
 	}
 	b.mu.Lock()
+	rep.UpdateMsg, rep.UpdateID = b.updateMsg, b.updateID
+	rep.UpdateStage, rep.UpdatePct, rep.UpdateLog = b.updStage, b.updPct, append([]string(nil), b.updLog...)
 	for id, chk := range b.mailChecks {
 		rep.MailChecks[id] = chk
 	}
@@ -736,3 +756,73 @@ func (ms *mapState) dialOff(proto string, prefer, off int) (net.Conn, bool, erro
 	}
 	return nil, false, last
 }
+
+// requestUpdate acts on "update now" from Hammerhead (id identifies the request). It only ever installs
+// what this machine's own auto-update would (the newest release from its configured server), and only
+// when auto-update is on. Caller holds b.mu.
+func (b *Blacktip) requestUpdate(id string) {
+	if id == b.updateID {
+		return // already handled, or in progress
+	}
+	b.updateID, b.updateMsg = id, ""
+	b.updStage, b.updPct, b.updLog = "starting", 0, nil
+	b.updNote("Update requested from the dashboard")
+	if !b.cfg.AutoUpdate || b.cfg.UpdateNow == nil {
+		b.updateMsg = "auto-update is off on this machine (set BLACKTIP_AUTO_UPDATE=1 and restart it)"
+		b.updStage = "failed"
+		b.updNote("Refused: " + b.updateMsg)
+		go b.report()
+		return
+	}
+	if !b.updating.CompareAndSwap(false, true) {
+		b.updateMsg = "another update is already running"
+		b.updStage = "failed"
+		b.updNote("Refused: " + b.updateMsg)
+		go b.report()
+		return
+	}
+	go func() {
+		defer b.updating.Store(false)
+		tag, err := b.cfg.UpdateNow(b.ctx, b.updProgress) // on success this restarts the process and does not return
+		b.mu.Lock()
+		switch {
+		case err != nil:
+			b.updateMsg = "update failed: " + err.Error()
+		case tag == "":
+			b.updateMsg = "already on the newest release"
+		default:
+			b.updateMsg = "updated to " + tag + ", restarting"
+		}
+		b.mu.Unlock()
+		b.report()
+	}()
+}
+
+// updNote adds a timestamped line to the update log. Caller holds b.mu.
+func (b *Blacktip) updNote(line string) {
+	b.updLog = append(b.updLog, time.Now().Format("15:04:05")+" "+line)
+	if len(b.updLog) > 200 {
+		b.updLog = b.updLog[len(b.updLog)-200:]
+	}
+}
+
+// updProgress is called by the updater as it works; Hammerhead gets a fresh report at most once a
+// second (and straight away for every new log line), so its progress bar follows along.
+func (b *Blacktip) updProgress(stage string, pct int, line string) {
+	b.mu.Lock()
+	b.updStage = stage
+	if pct >= 0 {
+		b.updPct = pct
+	}
+	if line != "" {
+		b.updNote(line)
+	}
+	send := line != "" || time.Since(b.updSent) > time.Second
+	if send {
+		b.updSent = time.Now()
+	}
+	b.mu.Unlock()
+	if send {
+		go b.report()
+	}
+}

cmd/blacktip/main.go

@@ -11,8 +11,12 @@ import (
 
 	"git.veillax.com/Veillax/blacktip"
 	"git.veillax.com/Veillax/reef/dotenv"
+	"git.veillax.com/Veillax/reef/selfupdate"
 )
 
+// version is set at build time (deploy/build.sh).
+var version = "dev"
+
 func env(k, def string) string {
 	if v := os.Getenv(k); v != "" {
 		return v
@@ -35,20 +39,37 @@ func main() {
 	acmeDNS := flag.String("acme-dns", os.Getenv("BLACKTIP_ACME_DNS"), "with -traefik: DNS-challenge provider (e.g. cloudflare) for wildcard certificates; its credentials go in this process's environment")
 	noACME := flag.Bool("no-acme", false, "with -traefik: serve Traefik's self-signed certificate instead of requesting Let's Encrypt ones")
 	flag.String("env", ".env", "file to read secrets and settings from")
+	autoUpdate := flag.Bool("auto-update", os.Getenv("BLACKTIP_AUTO_UPDATE") == "1", "check for new releases every few hours and update and restart by itself (Linux and macOS)")
+	showVersion := flag.Bool("version", false, "print the version and exit")
 	flag.Parse()
+	if *showVersion {
+		os.Stdout.WriteString("blacktip " + version + "\n")
+		return
+	}
 	if *hh == "" || *token == "" {
 		flag.Usage()
 		os.Exit(2)
 	}
+	upd := selfupdate.Config{Server: "https://git.veillax.com", Repo: "Veillax/blacktip", App: "blacktip", Current: version, Logf: log.Printf}
 	b, err := blacktip.New(blacktip.Config{
 		Hammerhead: strings.TrimRight(*hh, "/"), Token: *token, TunnelAddr: *tun, DataDir: *data, Docker: *dockerOn,
 		Traefik: blacktip.TraefikConfig{Path: *traefikPath, ACMEDNS: *acmeDNS, NoACME: *noACME},
+		Version: version, AutoUpdate: *autoUpdate,
+		UpdateNow: func(ctx context.Context, progress func(string, int, string)) (string, error) {
+			c := upd
+			c.Progress = func(e selfupdate.Event) { progress(e.Stage, e.Pct, e.Line) }
+			return selfupdate.CheckOnce(ctx, c)
+		},
 	})
 	if err != nil {
 		log.Fatal(err)
 	}
+	log.Printf("blacktip %s starting", version)
 	ctx, stop := signal.NotifyContext(context.Background(), os.Interrupt)
 	defer stop()
+	if *autoUpdate {
+		go selfupdate.Run(ctx, upd)
+	}
 	if err := b.Run(ctx); err != nil {
 		log.Fatal(err)
 	}

deploy/blacktip.service

@@ -0,0 +1,35 @@
+[Unit]
+Description=Blacktip: edge for tunnelled ports and websites
+Documentation=https://git.veillax.com/Veillax/blacktip
+After=network-online.target
+Wants=network-online.target
+
+[Service]
+User=blacktip
+Group=blacktip
+# The Traefik that ships with Blacktip; set BLACKTIP_TRAEFIK= (empty) in the env file for the built-in proxy.
+Environment=BLACKTIP_TRAEFIK=/usr/local/lib/blacktip/traefik
+EnvironmentFile=-/etc/blacktip/blacktip.env
+ExecStart=/usr/local/lib/blacktip/blacktip -data /var/lib/blacktip
+WorkingDirectory=/var/lib/blacktip
+Restart=on-failure
+RestartSec=3
+# A port range can open up to 1000 listeners at once.
+LimitNOFILE=65536
+
+# Ports 80 and 443 need this; nothing else is granted.
+AmbientCapabilities=CAP_NET_BIND_SERVICE
+CapabilityBoundingSet=CAP_NET_BIND_SERVICE
+NoNewPrivileges=true
+ProtectSystem=strict
+ReadWritePaths=/var/lib/blacktip /usr/local/lib/blacktip
+ProtectHome=true
+PrivateTmp=true
+ProtectKernelTunables=true
+ProtectControlGroups=true
+
+# To list this machine's Docker containers (BLACKTIP_DOCKER=1), let the service read
+# the Docker socket:   sudo usermod -aG docker blacktip   then restart it.
+
+[Install]
+WantedBy=multi-user.target

deploy/build.sh

@@ -0,0 +1,54 @@
+#!/bin/sh
+# Builds blacktip for every release platform and packs the archives into dist/.
+#
+#   deploy/build.sh [version]      version defaults to `git describe`
+#
+# Output:
+#   dist/bin/<os>_<arch>/blacktip and traefik             the raw binaries (the Docker image uses the linux ones)
+#   dist/blacktip_<version>_<os>_<arch>.tar.gz or .zip
+#   dist/SHA256SUMS
+#
+# Releases are published for linux/amd64 and windows/amd64 only. Set TARGETS="linux/arm64 darwin/arm64"
+# (any GOOS/GOARCH pair Go supports) to build something else by hand.
+set -eu
+NAME=blacktip
+cd "$(dirname "$0")/.."
+VERSION=${1:-$(git describe --tags --always 2>/dev/null || echo dev)}
+TARGETS=${TARGETS:-"linux/amd64 windows/amd64"}
+
+rm -rf dist
+mkdir -p dist/bin dist/stage
+for t in $TARGETS; do
+	os=${t%/*}
+	arch=${t#*/}
+	ext=""
+	[ "$os" = windows ] && ext=".exe"
+	out="dist/bin/${os}_${arch}"
+	mkdir -p "$out"
+	echo "building $NAME $VERSION for $os/$arch"
+	CGO_ENABLED=0 GOOS=$os GOARCH=$arch GOARM=7 \
+		go build -trimpath -ldflags "-s -w -X main.version=$VERSION" -o "$out/$NAME$ext" "./cmd/$NAME"
+
+	# the Traefik that Blacktip drives for http/https (see BLACKTIP_TRAEFIK)
+	sh deploy/fetch-traefik.sh "$os" "$arch" "$out"
+
+	pkg="${NAME}_${VERSION}_${os}_${arch}"
+	stage="dist/stage/$pkg"
+	mkdir -p "$stage"
+	cp "$out/$NAME$ext" "$out/traefik$ext" "$stage/"
+	for f in LICENSE README.md .env.example; do
+		[ -f "$f" ] && cp "$f" "$stage/"
+	done
+	if [ "$os" = linux ]; then
+		cp deploy/install.sh "deploy/$NAME.service" deploy/docker-compose.yml "$stage/"
+		chmod +x "$stage/install.sh"
+	fi
+	if [ "$os" = windows ] && command -v zip >/dev/null 2>&1; then
+		(cd dist/stage && zip -qr "../$pkg.zip" "$pkg")
+	else
+		tar -C dist/stage -czf "dist/$pkg.tar.gz" "$pkg"
+	fi
+done
+rm -rf dist/stage
+(cd dist && sha256sum $(ls | grep -E '\.(tar\.gz|zip)$') > SHA256SUMS)
+echo "done: $(ls dist | grep -cE '\.(tar\.gz|zip)$') archives in dist/"

deploy/docker-compose.yml

@@ -0,0 +1,20 @@
+# Run Blacktip with Docker on a public server:
+#   cp .env.example .env     (then set BLACKTIP_HAMMERHEAD and BLACKTIP_TOKEN)
+#   docker compose up -d
+#
+# Host networking is needed so Blacktip can open ports on the machine's own IP
+# addresses (including the same port on different IPs). Open the WireGuard UDP port
+# (51820 by default) and every port you create in the dashboard in the firewall.
+services:
+  blacktip:
+    image: git.veillax.com/veillax/blacktip:latest
+    restart: unless-stopped
+    network_mode: host
+    env_file: .env
+    volumes:
+      - blacktip-data:/data
+      # To list this machine's Docker containers as targets (BLACKTIP_DOCKER=1):
+      # - /var/run/docker.sock:/var/run/docker.sock:ro
+
+volumes:
+  blacktip-data:

deploy/fetch-traefik.sh

@@ -0,0 +1,29 @@
+#!/bin/sh
+# Downloads the official Traefik release for one platform and checks its checksum.
+#
+#   deploy/fetch-traefik.sh <os> <arch> <destination-dir>
+#
+# Blacktip ships this exact Traefik version, which is the one it was tested with.
+# Set TRAEFIK_VERSION to try another.
+set -eu
+OS=${1:?os} ARCH=${2:?arch} DEST=${3:?destination}
+VERSION=${TRAEFIK_VERSION:-3.7.16}
+case "$ARCH" in arm) ARCH=armv7 ;; esac
+EXT=tar.gz
+[ "$OS" = windows ] && EXT=zip
+BASE="https://github.com/traefik/traefik/releases/download/v$VERSION"
+FILE="traefik_v${VERSION}_${OS}_${ARCH}.$EXT"
+CACHE=${TRAEFIK_CACHE:-${TMPDIR:-/tmp}/traefik-cache}
+mkdir -p "$CACHE" "$DEST"
+[ -f "$CACHE/$FILE" ] || curl -fsSL -o "$CACHE/$FILE" "$BASE/$FILE"
+[ -f "$CACHE/checksums-$VERSION.txt" ] || curl -fsSL -o "$CACHE/checksums-$VERSION.txt" "$BASE/traefik_v${VERSION}_checksums.txt"
+want=$(grep " $FILE\$" "$CACHE/checksums-$VERSION.txt" | cut -d' ' -f1)
+[ -n "$want" ] || { echo "no checksum listed for $FILE" >&2; exit 1; }
+got=$(sha256sum "$CACHE/$FILE" | cut -d' ' -f1)
+[ "$want" = "$got" ] || { echo "checksum mismatch for $FILE" >&2; rm -f "$CACHE/$FILE"; exit 1; }
+if [ "$EXT" = zip ]; then
+	unzip -qo "$CACHE/$FILE" traefik.exe -d "$DEST"
+else
+	tar -xzf "$CACHE/$FILE" -C "$DEST" traefik
+fi
+echo "traefik $VERSION for $OS/$ARCH ready"

deploy/install.sh

@@ -0,0 +1,83 @@
+#!/bin/sh
+# Installs blacktip as a systemd service from the files in this folder.
+#
+#   sudo ./install.sh              install or upgrade (your settings and data are kept)
+#   sudo ./install.sh --start      the same, then start (or restart) the service
+#   sudo ./install.sh --uninstall  remove the service and binary (keeps the settings and data)
+#
+# Files: /usr/local/lib/blacktip/blacktip (linked from /usr/local/bin/blacktip), /etc/systemd/system/blacktip.service,
+#        /etc/blacktip/blacktip.env (your settings and secrets), /var/lib/blacktip (data).
+# Set DESTDIR=/some/dir to stage everything there without touching the system.
+set -eu
+NAME=blacktip
+HERE=$(cd "$(dirname "$0")" && pwd)
+ROOT=${DESTDIR:-}
+BIN=$ROOT/usr/local/bin/$NAME
+UNIT=$ROOT/etc/systemd/system/$NAME.service
+CONF=$ROOT/etc/$NAME
+ENVFILE=$CONF/$NAME.env
+DATA=$ROOT/var/lib/$NAME
+LIB=$ROOT/usr/local/lib/$NAME # the program lives here, owned by the service, so auto-update can replace it
+
+say() { printf '%s\n' "$*"; }
+real() { [ -z "${DESTDIR:-}" ]; } # are we touching the real system?
+
+if real; then
+	[ "$(id -u)" = 0 ] || { say "Run this as root:  sudo $0 $*"; exit 1; }
+	command -v systemctl > /dev/null 2>&1 || { say "systemd wasn't found. Run $NAME directly (see the README) or use Docker."; exit 1; }
+fi
+
+if [ "${1:-}" = "--uninstall" ]; then
+	if real; then
+		systemctl disable --now "$NAME" > /dev/null 2>&1 || true
+	fi
+	rm -f "$UNIT" "$BIN" "$LIB/$NAME" "$ROOT/usr/local/lib/$NAME/traefik"
+	if real; then
+		systemctl daemon-reload || true
+	fi
+	say "Removed $NAME. Left in place: $CONF and $DATA (delete them yourself if you want them gone)."
+	exit 0
+fi
+
+[ -f "$HERE/$NAME" ] || { say "Can't find the $NAME binary next to this script."; exit 1; }
+
+if real && ! id "$NAME" > /dev/null 2>&1; then
+	useradd --system --home-dir "/var/lib/$NAME" --shell /usr/sbin/nologin "$NAME"
+	say "Created the system user '$NAME'."
+fi
+
+mkdir -p "$ROOT/usr/local/lib/$NAME" "$ROOT/usr/local/bin" "$ROOT/etc/systemd/system" "$CONF" "$DATA"
+mkdir -p "$LIB"
+install -m 0755 "$HERE/$NAME" "$LIB/$NAME.new"
+mv -f "$LIB/$NAME.new" "$LIB/$NAME" # atomic, so upgrading a running service is safe
+rm -f "$BIN"
+LINK=/usr/local/lib/$NAME/$NAME
+[ -z "${DESTDIR:-}" ] || LINK=$LIB/$NAME # staging: point inside the staging folder
+ln -s "$LINK" "$BIN"
+if [ -f "$HERE/traefik" ]; then
+	install -m 0755 "$HERE/traefik" "$ROOT/usr/local/lib/$NAME/traefik.new"
+	mv -f "$ROOT/usr/local/lib/$NAME/traefik.new" "$ROOT/usr/local/lib/$NAME/traefik"
+fi
+install -m 0644 "$HERE/$NAME.service" "$UNIT"
+if [ ! -f "$ENVFILE" ]; then
+	install -m 0600 "$HERE/.env.example" "$ENVFILE"
+	say "Created $ENVFILE. Edit it before starting."
+fi
+if real; then
+	chown -R "$NAME:$NAME" "$DATA" "$LIB"
+fi
+
+if real; then
+	systemctl daemon-reload
+	systemctl enable "$NAME" > /dev/null 2>&1
+	if [ "${1:-}" = "--start" ] || systemctl is-active --quiet "$NAME"; then
+		systemctl restart "$NAME"
+		say "$NAME is running."
+	fi
+fi
+
+say "Installed $("$LIB/$NAME" -version 2> /dev/null || echo "$NAME")."
+say "Next:"
+say "  1. edit $ENVFILE"
+say "  2. systemctl start $NAME      (or run this again with --start)"
+say "  3. journalctl -u $NAME -f     to watch it"

deploy/publish-release.sh

@@ -0,0 +1,71 @@
+#!/bin/sh
+# Creates (or updates) the Gitea release for a tag and uploads what deploy/build.sh made.
+#
+#   TOKEN=<access token that can write releases> deploy/publish-release.sh v0.2.0
+#
+# In Gitea Actions GITHUB_SERVER_URL and GITHUB_REPOSITORY are already set. Safe to
+# re-run: an existing release is reused and assets with the same name are replaced.
+set -eu
+TAG=${1:?usage: publish-release.sh <tag>}
+: "${TOKEN:?set TOKEN to a Gitea access token that can write releases}"
+SERVER=${GITHUB_SERVER_URL:-${GITEA_SERVER_URL:-https://git.veillax.com}}
+REPO=${GITHUB_REPOSITORY:-Veillax/blacktip}
+API="$SERVER/api/v1/repos/$REPO"
+AUTH="Authorization: token $TOKEN"
+
+# a JSON helper without needing jq: any python will do
+PY=python3
+python3 -c 'pass' > /dev/null 2>&1 || PY=python
+json() { "$PY" -c "$1"; }
+
+# release notes: the commit subjects since the previous tag
+prev=$(git describe --tags --abbrev=0 "$TAG^" 2>/dev/null || true)
+if [ -n "$prev" ]; then
+	notes=$(git log --pretty='format:- %s' "$prev..$TAG")
+else
+	notes=$(git log --pretty='format:- %s' "$TAG")
+fi
+prerelease=false
+case "$TAG" in *-*) prerelease=true ;; esac
+
+body=$(NOTES="$notes" TAG="$TAG" PRE="$prerelease" json '
+import json, os
+print(json.dumps({"tag_name": os.environ["TAG"], "name": os.environ["TAG"], "body": os.environ["NOTES"],
+                  "draft": False, "prerelease": os.environ["PRE"] == "true"}))')
+
+# reuse the release when a failed job is re-run
+id=$(curl -fsS -H "$AUTH" "$API/releases/tags/$TAG" 2>/dev/null | json 'import sys, json; print(json.load(sys.stdin)["id"])' 2>/dev/null || true)
+if [ -z "$id" ]; then
+	echo "creating release $TAG"
+	id=$(curl -fsS -X POST -H "$AUTH" -H 'Content-Type: application/json' -d "$body" "$API/releases" | json 'import sys, json; print(json.load(sys.stdin)["id"])')
+else
+	echo "release $TAG already exists (id $id): replacing its files"
+fi
+
+# the ids of the release's assets with a given name (a failed upload can leave a partial one behind)
+asset_ids() {
+	curl -fsS -H "$AUTH" "$API/releases/$id/assets" | "$PY" -c 'import sys, json
+for a in json.load(sys.stdin):
+    if a["name"] == sys.argv[1]:
+        print(a["id"])' "$1"
+}
+
+for f in dist/*.tar.gz dist/*.zip dist/SHA256SUMS; do
+	[ -f "$f" ] || continue
+	name=$(basename "$f")
+	n=1
+	while :; do
+		for aid in $(asset_ids "$name"); do
+			curl -fsS -X DELETE -H "$AUTH" "$API/releases/$id/assets/$aid" > /dev/null
+		done
+		echo "uploading $name (attempt $n)"
+		if curl -fsS --max-time 1200 -X POST -H "$AUTH" -F "attachment=@$f" "$API/releases/$id/assets?name=$name" > /dev/null; then
+			break
+		fi
+		# large uploads can hit a proxy timeout (HTTP 502); try again
+		[ "$n" -lt 5 ] || { echo "giving up on $name after $n attempts" >&2; exit 1; }
+		n=$((n + 1))
+		sleep $((n * 10))
+	done
+done
+echo "published $SERVER/$REPO/releases/tag/$TAG"

go.mod

@@ -3,7 +3,7 @@ module git.veillax.com/Veillax/blacktip
 go 1.27.3
 
 require (
-	git.veillax.com/Veillax/reef v0.1.0
+	git.veillax.com/Veillax/reef v0.1.7
 	github.com/emersion/go-msgauth v0.7.0
 	golang.org/x/crypto v0.58.0
 )

go.sum

@@ -1,5 +1,13 @@
 git.veillax.com/Veillax/reef v0.1.0 h1:O0OhEKFx2CsvACJ20sfzJNjGsngomtfDdKdxu4ROpCs=
 git.veillax.com/Veillax/reef v0.1.0/go.mod h1:ZBUd/BARO5kkpUNTP81TTY1aQXLHFR6bKDhCxckjHso=
+git.veillax.com/Veillax/reef v0.1.3 h1:RxSq2xwaup1+MieAkhlvOTZnYwPf19thFHEAe/7VxsI=
+git.veillax.com/Veillax/reef v0.1.3/go.mod h1:ZBUd/BARO5kkpUNTP81TTY1aQXLHFR6bKDhCxckjHso=
+git.veillax.com/Veillax/reef v0.1.5 h1:BydjLJsfGgU4zEIqUsePJRjPi9NgbFdmvq0M8dvJCgM=
+git.veillax.com/Veillax/reef v0.1.5/go.mod h1:ZBUd/BARO5kkpUNTP81TTY1aQXLHFR6bKDhCxckjHso=
+git.veillax.com/Veillax/reef v0.1.6 h1:NgZ4u2Z3hJ+BYD/zX9lov8fox4s2i8txtYNOpIsikVo=
+git.veillax.com/Veillax/reef v0.1.6/go.mod h1:ZBUd/BARO5kkpUNTP81TTY1aQXLHFR6bKDhCxckjHso=
+git.veillax.com/Veillax/reef v0.1.7 h1:5C2udonlJac2xvDOE5e+zDxej+AbZ9ttrNSE4owmwuU=
+git.veillax.com/Veillax/reef v0.1.7/go.mod h1:ZBUd/BARO5kkpUNTP81TTY1aQXLHFR6bKDhCxckjHso=
 github.com/Microsoft/go-winio v0.6.4 h1:kJF2pamtYCWXf0xAT8sAkwKC0pMl2HYBrRPHAqyUc+g=
 github.com/Microsoft/go-winio v0.6.4/go.mod h1:1xl5JXG4ze/m74GH6Dc4Mwxfc3VL5siRVQjIAlHH07U=
 github.com/emersion/go-msgauth v0.7.0 h1:vj2hMn6KhFtW41kshIBTXvp6KgYSqpA/ZN9Pv4g1INc=