Step 01 of 06
Learn the concept
A service is not finished when the packages work. Someone needs one binary, one help screen, one version string and one place where configuration is resolved. The final shape should be boring enough to run at 03:00.
The ideas this is made of
Build flags shape the artifact
go build -o bin/beacond ./cmd/beacond writes a named binary instead of a temporary run. Operators and scripts can refer to bin/beacond consistently. Build flags should not hide required runtime settings; they create the artifact, not the environment it runs in.
ldflags stamp identity
-ldflags "-X main.version=1.2.3" sets a string variable at link time. Stamping version, commit and build time lets a running service answer what code it is. During incidents, I think this pod has the fix is not a diagnostic method.
A version endpoint is operational evidence
GET /version should return the service name, version, commit and build time. It must not expose secrets or local paths. The endpoint lets load balancers, humans and future automation confirm exactly which artifact is serving traffic.
Thin main keeps ownership clear
main parses config, creates loggers, opens stores, builds handlers, starts the scheduler and handles shutdown. It should not contain SQL, probing logic or JSON contract mapping. Thin main is not less important; it is where the service becomes a process.
package main
import "fmt"
var version = "dev"
func main() { fmt.Println(version) }Build this with go build -ldflags "-X main.version=1.0.0" and the printed value changes without editing source. Beacon uses the same mechanism for /version.
Run versus build
| Command | Purpose | Output |
|---|---|---|
| Development | Temporary binary |
| Artifact | Reusable file |
| User tool | GOBIN path |
| Stamp metadata | String variables |
What these are called on the job
Artifact — The built file delivered and run, such as
bin/beacond.ldflags — Linker flags passed by
go build, often used to set string variables.Version stamping — Embedding release identity into the binary at build time.