Server init and wiring

Grafana boots through a chain of cmd/ → cli/ → server/ → registry/. This page traces the path so you know where to put a hook.

Entry point

pkg/cmd/grafana/main.go defines a urfave/cli app with two subcommands:

• grafana cli — admin/plugin/db helpers (pkg/cmd/grafana-cli/).
• grafana server — start the HTTP server (pkg/cmd/grafana-server/).

A separate apiserver subcommand is conditionally added when the (enterprise) APIServerFactory is available.

grafana server boot

sequenceDiagram
    participant Main as main.go
    participant Cmd as cmd/grafana-server
    participant Srv as server.Server
    participant Wire as wire DI graph
    participant Reg as registry
    participant HTTP as HTTPServer
    Main->>Cmd: ServerCommand.Run
    Cmd->>Cmd: Parse config (setting.NewCfg)
    Cmd->>Srv: server.Initialize(cfg)
    Srv->>Wire: wire.Build (initializeServer)
    Wire-->>Srv: *Server with all dependencies
    Srv->>Reg: registry.Run (start background services)
    Reg->>HTTP: HTTPServer.Run (listen)

pkg/server/server.go holds a Server struct that wraps the wired-up components. server.Run(ctx) starts the registry, which in turn starts every BackgroundService and the HTTP server.

Wire DI

pkg/server/wire.go composes a single Wire injector. Each service domain typically exports a wire.NewSet (often called WireSet or ProvideXxx) and pkg/server/wire.go aggregates them all.

The generated file is pkg/server/wire_gen.go. To regenerate after editing wire.go:

make gen-go

Wire enforces no-cycles at codegen time and gives you a clear error if anything is missing.

Background services and the registry

pkg/registry/registry.go defines:

• BackgroundService — anything with Run(ctx) error that should run for the server lifetime.
• CanBeDisabled — optional knob so users can [<svc>] enabled = false something off.
• A registry that orders, starts, and gracefully shuts down all background services.

Examples of background services:

• The HTTP server itself (pkg/api/http_server.go).
• The ngalert scheduler (pkg/services/ngalert/schedule/).
• The plugin manager (pkg/plugins/manager/).
• The Live coordinator (pkg/services/live/).
• The query history pruner.

When you add a new long-running service, implement BackgroundService and add it to the registry in wire.go.

Modules

pkg/modules/ is a higher-level grouping of "what to run". A module bundles a set of background services into a logical mode (e.g. all, core, frontend-server, instrument). [server] modules = ... selects which modules start. This is the entry point for splitting Grafana into distinct deployment shapes.

Config loading

pkg/setting/setting.go parses configuration:

1. conf/defaults.ini — bundled defaults.
2. <workdir>/conf/custom.ini — user overrides (or --config flag).
3. --homepath and command-line flags.
4. Environment variables (GF_<SECTION>_<KEY>).

setting.Cfg is then injected into every service that needs it via Wire. See Configuration reference for the full key list.

Operators

pkg/operators/ is a registry for App SDK operators — Kubernetes-style controllers that reconcile resources. The package is imported with _ in main.go so its init() registers operators with the App SDK runtime.

Key source files

File	Purpose
pkg/cmd/grafana/main.go	grafana binary entry point
pkg/cmd/grafana-server/commands/server.go	grafana server command
pkg/server/server.go	Server struct + Run
pkg/server/wire.go	Wire DI graph (regen with make gen-go)
pkg/server/wire_gen.go	Generated injector
pkg/registry/registry.go	Background service controller
pkg/setting/setting.go	Config loader
pkg/modules/modules.go	Module grouping