observability

package
v0.3.1 Latest Latest
Warning

This package is not in the latest version of its module.

Go to latest
Published: Jun 2, 2026 License: MIT Imports: 13 Imported by: 0

Documentation

Overview

Package observability bootstraps the opt-in dev-time observability stack (Dozzle logs + Beszel metrics hub/agent). It owns the runtime-generated hub password — generated with crypto/rand on first use and persisted in the per-user config dir at 0600, mirroring the local CA private key in internal/tls — and the env files that inject the hub/agent configuration into the compose services. The proximo binary embeds no credential.

Index

Constants

View Source
const (

	// HubService is the in-stack hostname the agent reaches the hub on.
	HubService = "beszel"
	// HubPort is the port the Beszel hub listens on inside the stack.
	HubPort = 8090
)

Variables

This section is empty.

Functions

func Bootstrap

func Bootstrap(ctx context.Context, api HubAPI, stackDir, hubURL, email, password string) error

Bootstrap registers the metrics agent with the hub with no manual step: it waits for the hub, authenticates the seeded user, retrieves the hub public key and a universal registration token, and writes the agent env file consumed by the beszel-agent service. It is idempotent — on repeat runs the user and registration already exist, so it re-authenticates and re-fetches and the agent re-registers by fingerprint without creating a duplicate system.

func Email

func Email(tld string) string

Email returns the fixed, non-secret hub user email for a TLD. It is deterministic so it can also be substituted into the compose file as a sentinel without persisting anything. The domain is dotted (proximo.<tld>) on purpose: Beszel/PocketBase validates USER_EMAIL with a format check that rejects a bare single-label domain, so "proximo@test" fails its first-run migration and the hub crash-loops — "proximo@proximo.test" passes.

func EnsureSecret

func EnsureSecret() (string, error)

EnsureSecret returns the stored hub password, generating and persisting a new one (crypto/rand, 0600) on first use. It is idempotent: a stored secret is reused rather than regenerated.

func HubURL

func HubURL() string

HubURL is the in-stack URL the agent uses to reach the hub.

func Purge

func Purge(stackDir string) error

Purge removes the stored secret and the generated env files. Missing files are ignored so teardown is idempotent. stackDir may be empty when the stack was never materialized.

func SecretPath

func SecretPath() (string, error)

SecretPath returns the per-user path of the stored hub password.

func WriteAgentEnv

func WriteAgentEnv(stackDir, hubURL, key, token string) error

WriteAgentEnv writes the hub URL, public key, and registration token into stackDir/beszel-agent.env at 0600, consumed by the beszel-agent service.

func WriteHubEnv

func WriteHubEnv(stackDir, password string) error

WriteHubEnv writes the hub's generated password into stackDir/beszel-hub.env at 0600. The hub reads USER_PASSWORD from it to seed the first user.

Types

type HubAPI

type HubAPI interface {
	// WaitReady blocks until the hub answers as healthy or ctx is done.
	WaitReady(ctx context.Context) error
	// Authenticate logs in the seeded local user and returns an auth token.
	Authenticate(ctx context.Context, email, password string) (token string, err error)
	// PublicKey returns the hub's public SSH key the agent verifies against.
	PublicKey(ctx context.Context, authToken string) (string, error)
	// UniversalToken returns an enabled universal registration token the agent
	// self-registers with (idempotent: reuses the existing token).
	UniversalToken(ctx context.Context, authToken string) (string, error)
}

HubAPI is the subset of Beszel hub operations the bootstrap needs, behind an interface so the sequencing can be unit-tested against a stub without a live hub. The production implementation is *HubClient.

type HubClient

type HubClient struct {
	// BaseURL is the hub origin reachable from the host, e.g. http://127.0.0.1:443
	// fronted by Traefik, or a direct published port.
	BaseURL string
	HTTP    *http.Client
	// ReadyTimeout caps the readiness poll; PollInterval spaces the attempts.
	ReadyTimeout time.Duration
	PollInterval time.Duration
}

HubClient talks to the Beszel hub REST API (PocketBase + Beszel routes). The exact env/endpoints are upstream behaviors pinned to the henrygd/beszel image tag in docker-compose.yml; verify them on each image bump (see design risks).

func NewHubClient

func NewHubClient(baseURL string) *HubClient

NewHubClient returns a HubClient with sane defaults for the in-process bootstrap that runs inside the one-shot `up`.

func (*HubClient) Authenticate

func (c *HubClient) Authenticate(ctx context.Context, email, password string) (string, error)

Authenticate logs the seeded local user in via the PocketBase `users` collection. Per the Beszel maintainer the universal-token / getkey routes require a `users` token, not a `_superusers` one.

func (*HubClient) PublicKey

func (c *HubClient) PublicKey(ctx context.Context, authToken string) (string, error)

PublicKey fetches the hub public SSH key.

func (*HubClient) UniversalToken

func (c *HubClient) UniversalToken(ctx context.Context, authToken string) (string, error)

UniversalToken returns an enabled universal registration token. It reads the current token, then enables it (idempotent — re-enabling the same token is a no-op), mirroring the documented read-then-enable dance.

func (*HubClient) WaitReady

func (c *HubClient) WaitReady(ctx context.Context) error

WaitReady polls the PocketBase health endpoint until it answers 200.

Jump to

Keyboard shortcuts

? : This menu
/ : Search site
f or F : Jump to
y or Y : Canonical URL