docs: close pre-release documentation gaps

- Docker compose: ping_group_range sysctl, without which ping monitors
  silently report DOWN in containers
- README: data retention table (1000 checks / 5000 state changes per
  monitor, 200 logs, pruned automatically), group-alert limitation note
- config-as-code: apply is not atomic + re-run convergence, backup
  redaction footgun (/api/backup/export redacts by default), opsgenie
  example (provider count was stale at 9), ntfy auth keys

.gitea/workflows/release-binaries.yml

@@ -52,7 +52,3 @@ jobs:
           GORELEASER_FORCE_TOKEN: gitea
           GITEA_TOKEN: ${{ secrets.RELEASE_TOKEN }}
           GITEA_API_URL: http://gitea:3000/api/v1
-
-      # GitHub release relaying is handled by .github/workflows/mirror-release.yml,
-      # which runs on GitHub Actions when the push mirror delivers the tag and
-      # copies this run's Gitea release assets — no PAT needed on this side.

.github/workflows/mirror-release.yml

@@ -38,9 +38,7 @@ jobs:
             exit 1
           fi
 
-          # select() so an empty-string body produces an empty file — `// empty`
+          echo "$RESPONSE" | jq -r '.body // empty' > /tmp/release-notes.md
-          # treats "" as truthy and wrote a blank line, defeating this fallback.
-          echo "$RESPONSE" | jq -r '.body | select(. != null and . != "")' > /tmp/release-notes.md
 
           if [ ! -s /tmp/release-notes.md ]; then
             echo "Release ${TAG} from [Gitea](https://gitea.lerkolabs.com/lerkolabs/uptop/releases/tag/${TAG})" > /tmp/release-notes.md
@@ -64,11 +62,8 @@ jobs:
           GH_TOKEN: ${{ secrets.GITHUB_TOKEN }}
           TAG: ${{ github.ref_name }}
         run: |
-          PRERELEASE=""
-          case "$TAG" in *-*) PRERELEASE="--prerelease" ;; esac
           gh release create "$TAG" \
             --repo "$GITHUB_REPOSITORY" \
             --title "$TAG" \
             --notes-file /tmp/release-notes.md \
-            $PRERELEASE \
             /tmp/assets/*

.goreleaser.yaml

@@ -8,7 +8,6 @@ release:
   gitea:
     owner: lerkolabs
     name: uptop
-  prerelease: auto
 
 builds:
   - main: ./cmd/uptop
@@ -59,7 +58,5 @@ nfpms:
         dst: /usr/share/doc/uptop/LICENSE
         type: doc
 
-# Changelog generation must stay enabled: the --release-notes flag is consumed
+changelog:
-# by the changelog pipe, so disabling it silently drops the git-cliff notes
+  disable: true
-# (empty release body on v0.1.0-rc.1). With --release-notes set, GoReleaser
-# skips its own generation and uses the file.

Dockerfile

@@ -1,5 +1,5 @@
 # --- Stage 1: Builder ---
-FROM golang:1.26.4-alpine3.23@sha256:f23e8b227fb4493eabe03bede4d5a32d04092da71962f1fb79b5f7d1e6c2a17f AS builder
+FROM golang:1.26-alpine3.23@sha256:91eda9776261207ea25fd06b5b7fed8d397dd2c0a283e77f2ab6e91bfa71079d AS builder
 WORKDIR /app
 COPY go.mod go.sum ./
 RUN --mount=type=cache,target=/go/pkg/mod \

README.md

@@ -193,7 +193,7 @@ Export your Kuma backup JSON, then:
 
 ```bash
 curl -X POST http://localhost:8080/api/import/kuma \
-  -H "X-Uptop-Secret: your-secret" \
+  -H "X-Upkeep-Secret: your-secret" \
   -H "Content-Type: application/json" \
   -d @kuma-backup.json
 ```

docs/clustering.md

@@ -81,5 +81,5 @@ Set via `UPTOP_AGG_STRATEGY` on the leader.
 ## Security
 
 - Set `UPTOP_CLUSTER_SECRET` on all nodes. Without it, cluster API endpoints are unauthenticated.
-- Secrets are sent in HTTP headers (`X-Uptop-Secret`). Use TLS or a reverse proxy for production.
+- Secrets are sent in HTTP headers (`X-Upkeep-Secret`). Use TLS or a reverse proxy for production.
 - uptop warns on startup if the cluster secret is missing or if cluster mode is active without TLS.

internal/cluster/cluster.go

@@ -52,7 +52,7 @@ func runFollowerLoop(ctx context.Context, cfg Config, eng *monitor.Engine) {
 
 		req, _ := http.NewRequest("GET", cfg.PeerURL+"/api/health", nil)
 		if cfg.SharedKey != "" {
-			req.Header.Set("X-Uptop-Secret", cfg.SharedKey)
+			req.Header.Set("X-Upkeep-Secret", cfg.SharedKey)
 		}
 
 		resp, err := client.Do(req)

internal/cluster/cluster_test.go

@@ -113,7 +113,7 @@ func TestFollowerLoop_SendsSecret(t *testing.T) {
 	var receivedSecret string
 	srv := httptest.NewServer(http.HandlerFunc(func(w http.ResponseWriter, r *http.Request) {
 		mu.Lock()
-		receivedSecret = r.Header.Get("X-Uptop-Secret")
+		receivedSecret = r.Header.Get("X-Upkeep-Secret")
 		mu.Unlock()
 		w.WriteHeader(200)
 		w.Write([]byte("OK"))

internal/cluster/probe.go

@@ -90,7 +90,7 @@ func probeRegister(ctx context.Context, client *http.Client, cfg ProbeConfig) er
 		return err
 	}
 	req.Header.Set("Content-Type", "application/json")
-	req.Header.Set("X-Uptop-Secret", cfg.SharedKey)
+	req.Header.Set("X-Upkeep-Secret", cfg.SharedKey)
 	resp, err := client.Do(req)
 	if err != nil {
 		return err
@@ -108,7 +108,7 @@ func probeFetchAssignments(ctx context.Context, client *http.Client, cfg ProbeCo
 	if err != nil {
 		return nil, err
 	}
-	req.Header.Set("X-Uptop-Secret", cfg.SharedKey)
+	req.Header.Set("X-Upkeep-Secret", cfg.SharedKey)
 	resp, err := client.Do(req)
 	if err != nil {
 		return nil, err
@@ -180,7 +180,7 @@ func probeReportResults(ctx context.Context, client *http.Client, cfg ProbeConfi
 		return err
 	}
 	req.Header.Set("Content-Type", "application/json")
-	req.Header.Set("X-Uptop-Secret", cfg.SharedKey)
+	req.Header.Set("X-Upkeep-Secret", cfg.SharedKey)
 	resp, err := client.Do(req)
 	if err != nil {
 		return err

internal/importer/kuma_test.go

@@ -1,210 +0,0 @@
-package importer
-
-import (
-	"os"
-	"path/filepath"
-	"strings"
-	"testing"
-)
-
-func writeTemp(t *testing.T, content string) string {
-	t.Helper()
-	path := filepath.Join(t.TempDir(), "backup.json")
-	if err := os.WriteFile(path, []byte(content), 0o600); err != nil {
-		t.Fatal(err)
-	}
-	return path
-}
-
-func TestLoadKumaFileMissingFile(t *testing.T) {
-	_, err := LoadKumaFile(filepath.Join(t.TempDir(), "nope.json"))
-	if err == nil {
-		t.Fatal("expected error for missing file")
-	}
-}
-
-func TestLoadKumaFileMalformedInput(t *testing.T) {
-	cases := []struct {
-		name string
-		body string
-	}{
-		{"empty file", ""},
-		{"truncated JSON", `{"version": "1.23", "monitorList": [`},
-		{"not JSON", "definitely not json"},
-		{"wrong root type", `[1, 2, 3]`},
-		{"monitorList wrong type", `{"monitorList": {"a": 1}}`},
-		{"monitor field wrong type", `{"monitorList": [{"id": "not-an-int"}]}`},
-		{"notificationList wrong type", `{"notificationList": "oops"}`},
-	}
-	for _, tc := range cases {
-		t.Run(tc.name, func(t *testing.T) {
-			_, err := LoadKumaFile(writeTemp(t, tc.body))
-			if err == nil {
-				t.Fatalf("expected parse error for %s", tc.name)
-			}
-			if !strings.Contains(err.Error(), "parse JSON") {
-				t.Fatalf("expected wrapped parse error, got: %v", err)
-			}
-		})
-	}
-}
-
-func TestLoadKumaFileNullLists(t *testing.T) {
-	kb, err := LoadKumaFile(writeTemp(t, `{"version": "1.23", "monitorList": null, "notificationList": null}`))
-	if err != nil {
-		t.Fatal(err)
-	}
-	backup := ConvertKuma(kb)
-	if len(backup.Sites) != 0 || len(backup.Alerts) != 0 {
-		t.Fatalf("expected empty backup, got %d sites %d alerts", len(backup.Sites), len(backup.Alerts))
-	}
-}
-
-func TestConvertKumaSkipsMalformedNotificationConfig(t *testing.T) {
-	kb := &KumaBackup{
-		NotificationList: []KumaNotifEntry{
-			{ID: 1, Name: "broken", Config: "{not json"},
-			{ID: 2, Name: "good", Config: `{"type": "discord", "ntfyserverurl": "https://example.com/hook"}`},
-		},
-		MonitorList: []KumaMonitor{
-			{ID: 10, Name: "site", Type: "http", URL: "https://example.com", NotificationIDs: map[string]bool{"1": true}},
-		},
-	}
-	backup := ConvertKuma(kb)
-	if len(backup.Alerts) != 1 {
-		t.Fatalf("expected broken notification skipped, got %d alerts", len(backup.Alerts))
-	}
-	if backup.Alerts[0].Type != "discord" {
-		t.Fatalf("expected discord alert, got %q", backup.Alerts[0].Type)
-	}
-	if backup.Sites[0].AlertID != 0 {
-		t.Fatalf("site referencing skipped notification should keep AlertID 0, got %d", backup.Sites[0].AlertID)
-	}
-}
-
-func TestConvertKumaNtfyNotification(t *testing.T) {
-	kb := &KumaBackup{
-		NotificationList: []KumaNotifEntry{
-			{ID: 3, Name: "ntfy", Config: `{
-				"type": "ntfy",
-				"ntfyserverurl": "https://ntfy.example.com/",
-				"ntfytopic": "uptime",
-				"ntfyPriority": 4,
-				"ntfyAuthenticationMethod": "usernamePassword",
-				"ntfyusername": "u",
-				"ntfypassword": "p"
-			}`},
-		},
-	}
-	backup := ConvertKuma(kb)
-	if len(backup.Alerts) != 1 {
-		t.Fatalf("expected 1 alert, got %d", len(backup.Alerts))
-	}
-	a := backup.Alerts[0]
-	if a.Type != "ntfy" {
-		t.Fatalf("expected ntfy, got %q", a.Type)
-	}
-	if a.Settings["url"] != "https://ntfy.example.com" {
-		t.Fatalf("expected trailing slash trimmed, got %q", a.Settings["url"])
-	}
-	if a.Settings["topic"] != "uptime" || a.Settings["priority"] != "4" {
-		t.Fatalf("unexpected settings: %v", a.Settings)
-	}
-	if a.Settings["username"] != "u" || a.Settings["password"] != "p" {
-		t.Fatalf("expected credentials mapped, got %v", a.Settings)
-	}
-}
-
-func TestConvertKumaUnknownNotificationFallsBackToWebhook(t *testing.T) {
-	kb := &KumaBackup{
-		NotificationList: []KumaNotifEntry{
-			{ID: 4, Name: "matrix", Config: `{"type": "matrix", "ntfyserverurl": "https://example.com/hook"}`},
-		},
-	}
-	backup := ConvertKuma(kb)
-	if len(backup.Alerts) != 1 || backup.Alerts[0].Type != "webhook" {
-		t.Fatalf("expected webhook fallback, got %+v", backup.Alerts)
-	}
-}
-
-func TestConvertKumaHTTPMonitor(t *testing.T) {
-	kb := &KumaBackup{
-		NotificationList: []KumaNotifEntry{
-			{ID: 1, Name: "hook", Config: `{"type": "slack", "ntfyserverurl": "https://example.com/hook"}`},
-		},
-		MonitorList: []KumaMonitor{{
-			ID:              7,
-			Name:            "web",
-			Type:            "http",
-			URL:             "https://example.com",
-			Interval:        60,
-			Timeout:         30,
-			MaxRetries:      2,
-			Method:          "GET",
-			AcceptedCodes:   []string{"200", "301"},
-			IgnoreTLS:       true,
-			ExpiryNotif:     true,
-			Active:          false,
-			NotificationIDs: map[string]bool{"1": true},
-		}},
-	}
-	backup := ConvertKuma(kb)
-	if len(backup.Sites) != 1 {
-		t.Fatalf("expected 1 site, got %d", len(backup.Sites))
-	}
-	s := backup.Sites[0]
-	if s.URL != "https://example.com" || !s.CheckSSL || !s.IgnoreTLS {
-		t.Fatalf("http fields not mapped: %+v", s)
-	}
-	if !s.Paused {
-		t.Fatal("inactive monitor should import paused")
-	}
-	if s.AcceptedCodes != "200,301" {
-		t.Fatalf("expected joined accepted codes, got %q", s.AcceptedCodes)
-	}
-	if s.AlertID != 1 {
-		t.Fatalf("expected alert mapped, got %d", s.AlertID)
-	}
-}
-
-func TestConvertKumaPushMonitorGetsToken(t *testing.T) {
-	kb := &KumaBackup{
-		MonitorList: []KumaMonitor{{ID: 1, Name: "push", Type: "push", Active: true}},
-	}
-	backup := ConvertKuma(kb)
-	token := backup.Sites[0].Token
-	if len(token) != 32 {
-		t.Fatalf("expected 32-char hex token, got %q", token)
-	}
-}
-
-func TestConvertKumaNonNumericNotificationID(t *testing.T) {
-	kb := &KumaBackup{
-		MonitorList: []KumaMonitor{{
-			ID:              1,
-			Name:            "site",
-			Type:            "http",
-			NotificationIDs: map[string]bool{"abc": true},
-		}},
-	}
-	backup := ConvertKuma(kb)
-	if backup.Sites[0].AlertID != 0 {
-		t.Fatalf("non-numeric notification ID should not map, got %d", backup.Sites[0].AlertID)
-	}
-}
-
-func TestConvertKumaGroupAndChildren(t *testing.T) {
-	kb := &KumaBackup{
-		MonitorList: []KumaMonitor{
-			{ID: 1, Name: "grp", Type: "group", Active: true},
-			{ID: 2, Name: "ping", Type: "ping", Hostname: "10.0.0.1", Parent: 1, Active: true},
-		},
-	}
-	backup := ConvertKuma(kb)
-	if backup.Sites[0].Type != "group" {
-		t.Fatalf("expected group type, got %q", backup.Sites[0].Type)
-	}
-	if backup.Sites[1].ParentID != 1 || backup.Sites[1].Hostname != "10.0.0.1" {
-		t.Fatalf("child not mapped: %+v", backup.Sites[1])
-	}
-}

internal/monitor/monitor.go

@@ -115,14 +115,10 @@ func newEngine(s store.Store, allowPrivateTargets bool) *Engine {
 	}
 }
 
-// SetInsecureSkipVerify must be called before Start: the field is read by
-// checker goroutines without synchronization.
 func (e *Engine) SetInsecureSkipVerify(skip bool) {
 	e.insecureSkipVerify = skip
 }
 
-// SetMaintRetention must be called before Start: the field is read by the
-// maintenance prune goroutine without synchronization.
 func (e *Engine) SetMaintRetention(d time.Duration) {
 	e.maintRetention = d
 }
@@ -1047,8 +1043,6 @@ func (e *Engine) EnqueueProbeCheck(siteID int, nodeID string, latencyNs int64, i
 	e.enqueueWrite(writeProbeCheck{siteID: siteID, nodeID: nodeID, latencyNs: latencyNs, isUp: isUp})
 }
 
-// SetAggStrategy must be called before Start: the field is read by the probe
-// aggregation path without synchronization.
 func (e *Engine) SetAggStrategy(strategy AggregationStrategy) {
 	e.aggStrategy = strategy
 }

internal/server/server.go

@@ -127,7 +127,7 @@ func (s *Server) routes() http.Handler {
 }
 
 func (s *Server) requireAuth(r *http.Request) bool {
-	return s.cfg.ClusterKey != "" && checkSecret(r.Header.Get("X-Uptop-Secret"), s.cfg.ClusterKey)
+	return s.cfg.ClusterKey != "" && checkSecret(r.Header.Get("X-Upkeep-Secret"), s.cfg.ClusterKey)
 }
 
 func (s *Server) handlePush(w http.ResponseWriter, r *http.Request) {
@@ -159,7 +159,7 @@ func (s *Server) handleHealth(w http.ResponseWriter, r *http.Request) {
 		http.Error(w, "Method not allowed", http.StatusMethodNotAllowed)
 		return
 	}
-	if s.cfg.ClusterKey != "" && !checkSecret(r.Header.Get("X-Uptop-Secret"), s.cfg.ClusterKey) {
+	if s.cfg.ClusterKey != "" && !checkSecret(r.Header.Get("X-Upkeep-Secret"), s.cfg.ClusterKey) {
 		http.Error(w, "Unauthorized", http.StatusUnauthorized)
 		return
 	}

internal/server/server_test.go

@@ -141,7 +141,7 @@ func authReq(method, url, secret string, body []byte) (*http.Response, error) {
 		return nil, err
 	}
 	if secret != "" {
-		req.Header.Set("X-Uptop-Secret", secret)
+		req.Header.Set("X-Upkeep-Secret", secret)
 	}
 	return http.DefaultClient.Do(req)
 }

internal/tui/data.go

@@ -104,7 +104,7 @@ func (m *Model) refreshLive() {
 		ordered = filterSites(ordered, m.filterText)
 	}
 	m.sites = ordered
-	m.refreshLogContent()
+	m.logViewport.SetContent(strings.Join(m.engine.GetLogs(), "\n"))
 
 	if m.currentTab == 0 && m.selectedID != 0 {
 		for i, s := range m.sites {

internal/tui/tab_logs.go

@@ -82,15 +82,18 @@ func (m Model) renderLogLine(line string) string {
 	return fmt.Sprintf("  %s  %s", tag, msg)
 }
 
-// refreshLogContent rebuilds the log viewport from the full engine log list,
+func (m Model) viewLogsTab() string {
-// filtering before windowing so the entry count and "(n hidden)" reflect all
+	content := m.logViewport.View()
-// logs, not just the visible viewport slice.
+	if strings.TrimSpace(content) == "" || content == "Waiting for logs..." {
-func (m *Model) refreshLogContent() {
+		return m.emptyState("No log entries yet.", "Logs appear as monitors run checks")
+	}
+
+	lines := strings.Split(content, "\n")
 	var rendered []string
 	total := 0
 	shown := 0
 
-	for _, line := range m.engine.GetLogs() {
+	for _, line := range lines {
 		if strings.TrimSpace(line) == "" {
 			continue
 		}
@@ -103,27 +106,18 @@ func (m *Model) refreshLogContent() {
 		rendered = append(rendered, m.renderLogLine(line))
 	}
 
-	m.logTotal = total
-	m.logShown = shown
-	m.logViewport.SetContent(strings.Join(rendered, "\n"))
-}
-
-func (m Model) viewLogsTab() string {
-	if m.logTotal == 0 {
-		return m.emptyState("No log entries yet.", "Logs appear as monitors run checks")
-	}
-
 	filterLabel := "All"
 	if m.logFilterImportant {
 		filterLabel = "Important"
 	}
 
 	header := m.st.subtleStyle.Render(fmt.Sprintf(
-		"  %d entries  Filter: %s", m.logShown, filterLabel))
+		"  %d entries  Filter: %s", shown, filterLabel))
 
-	if m.logFilterImportant && m.logShown < m.logTotal {
+	if m.logFilterImportant && shown < total {
-		header += m.st.subtleStyle.Render(fmt.Sprintf("  (%d hidden)", m.logTotal-m.logShown))
+		header += m.st.subtleStyle.Render(fmt.Sprintf("  (%d hidden)", total-shown))
 	}
 
+	m.logViewport.SetContent(strings.Join(rendered, "\n"))
 	return "\n" + header + "\n\n" + m.logViewport.View()
 }

internal/tui/tui.go

@@ -121,8 +121,6 @@ type Model struct {
 
 	logViewport        viewport.Model
 	logFilterImportant bool
-	logTotal           int
-	logShown           int
 
 	historyViewport viewport.Model
 	historyChanges  []models.StateChange

internal/tui/update.go

@@ -527,7 +527,6 @@ func (m *Model) handleDashboardKey(msg tea.KeyMsg) (tea.Model, tea.Cmd) {
 	case "f":
 		if m.state == stateLogs {
 			m.logFilterImportant = !m.logFilterImportant
-			m.refreshLogContent()
 			return m, nil
 		}
 	case "tab":