config

Documentation

Overview

Package config loads and validates Githome's runtime configuration from the environment (with an optional file overlay) into a single immutable Config.

Precedence is defaults, then an optional KEY=VALUE file pointed to by GITHOME_CONFIG_FILE, then GITHOME_* environment variables (highest). URLs are parsed once at startup and handed to the presenter layer so every response builds links from the configured host, never a hardcoded one.

Index

• Variables
• type Config
  • func Load() (Config, error)
  • func (c Config) RepoRoot() string
  • func (c Config) Validate() error
• type Listen
• type Log
• type Markup
• type RateLimit
• type Secrets
• type Server
• type URLs
• type Web
• type Worker

Variables

var Version = "dev"

Version is the build version, set at link time with -ldflags "-X github.com/tamnd/githome/config.Version=<v>". It is reported by the /healthz endpoint and stamped onto the default logger.

Types

type Config

type Config struct {
	URLs            URLs
	Listen          Listen
	DatabaseURL     string // GITHOME_DATABASE_URL; scheme selects the dialect
	DBPoolSize      int    // GITHOME_DB_POOL_SIZE; Postgres max-open-connections, default 25
	DataDir         string // GITHOME_DATA_DIR; bare repos live under DataDir/repos
	GitBinaryPath   string // GITHOME_GIT_BINARY; resolved on PATH when empty
	GitBackend      string // GITHOME_GIT_BACKEND; auto|gogit|gitcli|git2go
	RateLimit       RateLimit
	Secrets         Secrets
	Worker          Worker
	Log             Log
	Server          Server
	Web             Web
	Markup          Markup
	ShutdownTimeout time.Duration // GITHOME_SHUTDOWN_TIMEOUT; default 30s
	Env             string        // GITHOME_ENV; "production" switches slog to JSON
}

Config is the fully resolved server configuration. It is built once by Load and treated as immutable afterwards.

func Load

func Load() (Config, error)

Load builds a Config from defaults, an optional file overlay, and the environment, in that order of increasing precedence. It then resolves the derived URLs and validates the result.

func (Config) RepoRoot

func (c Config) RepoRoot() string

RepoRoot is the directory that holds the bare git repositories.

func (Config) Validate

func (c Config) Validate() error

Validate checks that the resolved configuration is internally consistent and safe to serve from. In particular it refuses to run with base URLs that point at an upstream GitHub host, since presenters build every link from these and a misconfiguration would emit the wrong host in responses.

type Listen

type Listen struct {
	HTTP string // GITHOME_LISTEN_HTTP  default ":3000"
	SSH  string // GITHOME_LISTEN_SSH   default ":2222"
}

Listen holds the bind addresses for the two listeners.

type Log

type Log struct {
	Level  string // GITHOME_LOG_LEVEL   debug|info|warn|error  default info
	Format string // GITHOME_LOG_FORMAT  json|text; empty resolves from Env
}

Log configures the structured logger.

type Markup

type Markup struct {
	CamoSecret        []byte // GITHOME_CAMO_SECRET; empty disables off-host image proxying
	CamoBaseURL       string // GITHOME_CAMO_BASE_URL; defaults to {HTML base}/camo
	MaxHighlightBytes int    // GITHOME_MARKUP_MAX_HIGHLIGHT_BYTES; a larger blob renders unhighlighted (logged), default 5 MiB
}

Markup configures the shared GFM renderer and the off-host image proxy. The renderer is built once at boot and shared by the web front and the REST text/html media type, so both surfaces apply one allowlist and one set of link rules. CamoSecret is the HMAC key for the camo image proxy: with it empty, off-host images are left as direct links rather than proxied through camo.

type RateLimit

type RateLimit struct {
	AuthedPerHour int           // GITHOME_RL_AUTHED_PER_HOUR    default 5000
	AnonPerHour   int           // GITHOME_RL_ANON_PER_HOUR      default 60
	GraphQLPoints int           // GITHOME_RL_GRAPHQL_POINTS     default 5000
	SearchPerMin  int           // GITHOME_RL_SEARCH_PER_MIN     default 30
	Window        time.Duration // fixed 1h to match GitHub reset semantics
}

RateLimit configures the per-actor rate-limit buckets that back the x-ratelimit-* headers and the /rate_limit endpoint.

type Secrets

type Secrets struct {
	SessionKey            []byte // GITHOME_SESSION_KEY  (>= 32 bytes)
	TokenPepper           []byte // GITHOME_TOKEN_PEPPER (>= 16 bytes)
	SSHHostKey            []byte // GITHOME_SSH_HOST_KEY or GITHOME_SSH_HOST_KEY_FILE
	WebhookSigningDefault []byte // GITHOME_WEBHOOK_SECRET
}

Secrets holds the sensitive material the server needs. Values may be supplied inline or, for the SSH host key, via a *_FILE indirection.

type Server

type Server struct {
	ReadHeaderTimeout time.Duration // GITHOME_HTTP_READ_HEADER_TIMEOUT  default 10s
	ReadTimeout       time.Duration // GITHOME_HTTP_READ_TIMEOUT         default 0 (off; git streams)
	WriteTimeout      time.Duration // GITHOME_HTTP_WRITE_TIMEOUT        default 0 (off; git streams)
	IdleTimeout       time.Duration // GITHOME_HTTP_IDLE_TIMEOUT         default 120s
	MaxHeaderBytes    int           // GITHOME_HTTP_MAX_HEADER_BYTES     default 1 MiB
	MaxBodyBytes      int64         // GITHOME_HTTP_MAX_BODY_BYTES       default 25 MiB; JSON API only
	MaxBlobBytes      int64         // GITHOME_GIT_MAX_BLOB_BYTES        default 100 MiB; -1 disables
}

Server holds the HTTP server hardening knobs. The two whole-request deadlines default to zero on purpose: git smart-HTTP clone and push stream a single response or request body for as long as a multi-gigabyte transfer takes, and a blanket ReadTimeout or WriteTimeout would sever those mid-transfer. An operator who fronts the JSON API on a separate listener with no git traffic can set them. The always-safe guards (header read deadline, idle keep-alive reaping, header size cap, and the JSON request-body cap) are on by default.

type URLs

type URLs struct {
	API     *url.URL // GITHOME_API_BASE_URL   e.g. https://git.example.com/api/v3
	HTML    *url.URL // GITHOME_HTML_BASE_URL  e.g. https://git.example.com
	GraphQL *url.URL // GITHOME_GRAPHQL_URL    e.g. https://git.example.com/api/graphql
	SSHHost string   // GITHOME_GIT_SSH_HOST   e.g. git.example.com
	SSHPort int      // GITHOME_GIT_SSH_PORT   default 22
	// contains filtered or unexported fields
}

URLs are the resolved external base URLs. API and GraphQL default to the HTML base plus the GHES-style suffixes when not set explicitly.

type Web

type Web struct {
	Enabled  bool   // GITHOME_WEB_ENABLED   default true
	SiteName string // GITHOME_WEB_SITE_NAME default "Githome"
}

Web configures the server-rendered HTML front. It is enabled by default and shares the process, the domain layer, and the session secret with the API; disabling it leaves only the REST, GraphQL, and git surfaces mounted.

type Worker

type Worker struct {
	Concurrency int           // GITHOME_WORKER_CONCURRENCY  default GOMAXPROCS
	PollEvery   time.Duration // GITHOME_WORKER_POLL         default 2s
}

Worker configures the background job pool.