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
- func Bootstrap(ctx context.Context, api HubAPI, stackDir, hubURL, email, password string) error
- func Email(tld string) string
- func EnsureSecret() (string, error)
- func HubURL() string
- func Purge(stackDir string) error
- func SecretPath() (string, error)
- func WriteAgentEnv(stackDir, hubURL, key, token string) error
- func WriteHubEnv(stackDir, password string) error
- type HubAPI
- type HubClient
- func (c *HubClient) Authenticate(ctx context.Context, email, password string) (string, error)
- func (c *HubClient) PublicKey(ctx context.Context, authToken string) (string, error)
- func (c *HubClient) UniversalToken(ctx context.Context, authToken string) (string, error)
- func (c *HubClient) WaitReady(ctx context.Context) error
Constants ¶
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 ¶
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 ¶
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 ¶
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 Purge ¶
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 ¶
SecretPath returns the per-user path of the stored hub password.
func WriteAgentEnv ¶
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 ¶
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 ¶
NewHubClient returns a HubClient with sane defaults for the in-process bootstrap that runs inside the one-shot `up`.
func (*HubClient) Authenticate ¶
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) UniversalToken ¶
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.