Content Management that can withstand the plundering hoards

Runtime configuration

Use this reference to configure Viking processes and inspect their defaults. For Kubernetes-managed sites use Website settings so the operator can reconcile changes. Hand-editing generated Deployments is usually temporary: reconciliation replaces managed settings. Commands and paths below are relative to the repository root unless a directory is named.

Flags take precedence over their supported environment fallbacks. CMS/frontend use Go boolean values such as true/false and durations such as 500ms, 1s, 5m, 1h. An address :8080 listens on all interfaces; use 127.0.0.1:8080 for a local process you do not want reachable from the network. Separate processes need different ports when running on the same host.

CMS

Authentication values are separate files in auth-secret-dir; see authentication Secret.

Flag Environment Default Meaning
--listen VIKING_LISTEN :8080 Authenticated API/editor and public OAuth endpoints
--admin-listen VIKING_ADMIN_LISTEN :8081 Internal health/readiness/metrics; no authentication
--private-root VIKING_PRIVATE_ROOT /cms Writable private project/assets/packages
--published-root VIKING_PUBLISHED_ROOT /www Writable releases and active pointer; frontend mounts read-only
--webui-dir VIKING_WEBUI_DIR /web Built editor directory; explicit empty disables directory serving and uses the fallback page
--retain-releases VIKING_RETAIN_RELEASES 0 Historical release count after grace period; negatives clamp to zero
--site-domain VIKING_SITE_DOMAIN empty Public domain for absolute sitemap URLs
--website-namespace VIKING_WEBSITE_NAMESPACE empty Namespace for asynchronous Website status writes
--website-name VIKING_WEBSITE_NAME empty Website name for status writes; configure with namespace
--auth-secret-dir VIKING_AUTH_SECRET_DIR /etc/viking/auth Directory with one auth key per file
--cookie-secure VIKING_COOKIE_SECURE true Secure session/state cookies and HTTPS callback scheme
--csrf-secure VIKING_CSRF_SECURE cookie-secure value unless explicitly set Secure CSRF cookie and expected same-origin scheme
--csrf-cookie VIKING_CSRF_COOKIE viking_csrf when empty CSRF cookie name, separate from the login cookie
--allow-insecure-auth-http VIKING_ALLOW_INSECURE_AUTH_HTTP false Allow HTTP IdP endpoints only on localhost/127.0.0.1/::1 for development
--cms-hostname VIKING_CMS_HOSTNAME empty, then auth cmsHostname Validate request hostname for OAuth redirects; port is ignored by pin comparison

Empty environment values generally fall back to defaults; use an explicit flag when empty has meaning. An invalid VIKING_RETAIN_RELEASES integer prevents startup. Invalid boolean environment values fall back to the default; explicit invalid boolean flags are rejected. Browser requests use session-bound CSRF tokens.

CMS listener timeout values are: Public: header 10s, read 60s, write 120s, idle 120s. Admin: header 10s, read 30s, write 60s, idle 60s. Shutdown uses a shared 15s context. Frontend timeout flags apply to the frontend process. The CMS remains a single replica and uses Recreate updates because login/CSRF state and publishing locks are process-local.

Volume preparation subcommand

cms prepare-volumes is an operator init-container command, not an HTTP server. It recursively changes ownership without following symlinks. It needs permission to chown the storage and must not be pointed at arbitrary system directories.

Flag Environment Default
--private-root VIKING_PRIVATE_ROOT /cms
--published-root VIKING_PUBLISHED_ROOT /www
--uid none 65532
--gid none 65532

Public frontend

The public frontend reads published files independently of the CMS and sign-in service.

Flag Environment Default Meaning
--root VIKING_ROOT /www/current Published document root, normally a symlink
--listen VIKING_LISTEN :8080 Public file listener
--admin-listen VIKING_ADMIN_LISTEN :8081 Internal health/readiness/metrics
--cache-control VIKING_CACHE_CONTROL public, max-age=0, must-revalidate Normal response caching policy
--cache-control-assets VIKING_CACHE_CONTROL_ASSETS empty Optional separate policy for content-hashed filenames
--index (repeatable) VIKING_INDEX (comma-separated) index.html Index filenames in preference order; explicit flag list replaces env list
--trust-proxy VIKING_TRUST_PROXY false Trust forwarded client address for logs; require exclusive trusted-proxy access
--root-freshness VIKING_ROOT_FRESHNESS 1s Cache resolved root symlink; 0 re-resolves for every request
--max-header-bytes VIKING_MAX_HEADER_BYTES 65536 Header size limit
--read-header-timeout VIKING_READ_HEADER_TIMEOUT 5s Header read budget
--read-timeout VIKING_READ_TIMEOUT 30s Whole request read budget
--write-timeout VIKING_WRITE_TIMEOUT 30s Response write budget
--idle-timeout VIKING_IDLE_TIMEOUT 120s Idle connection budget
--shutdown-timeout VIKING_SHUTDOWN_TIMEOUT 10s Public graceful drain
--admin-shutdown-timeout VIKING_ADMIN_SHUTDOWN_TIMEOUT 5s Admin graceful drain, concurrent with public drain

Durations/root freshness cannot be negative; header limit must be positive. Zero timeouts disable the corresponding timeout. Invalid numeric/duration/bool environment values fall back to defaults; invalid explicit flags are errors.

Controller

For local execution, standard Kubernetes client configuration uses your selected kubeconfig; inside a pod it uses its ServiceAccount. There is no general VIKING_* equivalent for every controller flag.

Flag Supported environment fallback Default Meaning
--metrics-addr none :8080 Internal metrics and versioned health/readiness
--health-probe-addr none 0 (disabled) Optional second native-format health listener
--leader-elect none false Only elected controller reconciles when running several
--leader-election-id none viking-cms-controller Kubernetes Lease lock name
--frontend-image none viking-cms-frontend:latest Image reconciled onto all generated frontend Deployments
--cms-image none viking-cms-cms:latest Image reconciled onto all generated CMS/init containers
--dns-namespace VIKING_DNS_NAMESPACE kube-system Deprecated; has no effect
--dns-label VIKING_DNS_LABEL k8s-app=kube-dns Deprecated, ignored
--ipseity-namespace VIKING_IPSEITY_NAMESPACE empty Restrict provider discovery namespace
--ipseity-deployment VIKING_IPSEITY_DEPLOYMENT empty Select provider Deployment
--ipseity-ingress VIKING_IPSEITY_INGRESS empty Select provider Ingress
--ipseity-admin-realm VIKING_IPSEITY_ADMIN_REALM ipseity Home realm of initial administrator
--ipseity-admin-subject VIKING_IPSEITY_ADMIN_SUBJECT adrian Existing home identity for initial administrator
--zap-devel VIKING_ZAP_DEVEL false Development logging; production uses JSON Info

Changing controller image arguments changes reconciled workloads for existing Websites as well as new ones. Manage rollout scope before switching shared images. Ipseity selectors/default identities are explained in Ipseity operations.

Build identity and HTTP headers

The application version identifies the running CMS, Frontend or Controller. Unstamped local builds report dev. Content release IDs and theme versions are separate identifiers.

Every HTTP listener sends Server: Viking <Component> <version>, including successful responses, errors, redirects, OAuth endpoints, probes and metrics. Ingress and reverse proxies must preserve the upstream header. Compare the public response with a direct component response if a proxy name appears. See observability for version checks.