Documentation
¶
Index ¶
Constants ¶
const ( // EnvProd - a live site, the default: templates cached, the modules' // files the binary's, a session key required, TLS to a remote // database. EnvProd = "prod" // EnvLocal - development: a debug log, templates read again on every // request, the modules' files from their source directories first, // no TLS default for a remote database. EnvLocal = "local" )
The environments a site runs in (env / APP_ENV): LoadPath accepts these two only.
const ( DriverMySQL = "mysql" DriverPostgres = "postgres" )
The database servers DBConfig.Driver names.
const SQLModeServerDefault = "server"
SQLModeServerDefault - DBConfig.SQLMode value meaning "don't set a session sql_mode".
Variables ¶
This section is empty.
Functions ¶
Types ¶
type Config ¶
type Config struct {
Env string `yaml:"env" env:"APP_ENV" env-default:"prod"`
Port int `yaml:"port" env:"APP_PORT"`
DB DBConfig `yaml:"db"`
Session SessionConfig `yaml:"session"`
Timeouts TimeoutConfig `yaml:"timeouts"`
Email EmailConfig `yaml:"email"`
Recaptcha RecaptchaConfig `yaml:"recaptcha"`
OAuth OAuthConfig `yaml:"oauth"`
// SecretsKey - the key the secrets kept in the database are sealed
// with (the outside services' keys saved in the admin, the users'
// two-factor secrets; internal/lib/secretbox): a long random string. "new,old"
// while replacing it - the old one still opens what it sealed. Empty -
// they are kept unsealed.
SecretsKey string `yaml:"secrets_key" env:"SECRETS_KEY"`
// PublicBaseURL - the site's canonical origin (e.g. https://www.example.com);
// when set, it overrides the one saved in Site information (service.SiteURL),
// so a copy of the production database keeps this site's URL. Empty - the
// admin's, else derived from the request.
PublicBaseURL string `yaml:"public_base_url" env:"PUBLIC_BASE_URL"`
// PageCacheMaxAge - seconds a shared cache (a CDN in front of the site)
// may keep a guest's page (middleware.PageCacheMiddleware: Cache-Control
// "public, s-maxage=…" on guests' HTML, "private, no-store" on the rest).
// 0 - off.
PageCacheMaxAge int `yaml:"page_cache_max_age" env:"PAGE_CACHE_MAX_AGE"`
// TrustedProxies - the proxies in front of the site whose
// X-Forwarded-For / X-Real-IP give the visitor's address (addresses or
// networks: 10.0.0.5, 172.16.0.0/12; httputil.ClientIP). Empty -
// loopback only, a web server on the same host.
TrustedProxies []string `yaml:"trusted_proxies" env:"TRUSTED_PROXIES" env-separator:","`
// Theme - the site theme: a directory under themes/ (see
// paths.SetTheme). Empty = engine templates only.
Theme string `yaml:"theme" env:"THEME"`
// ThemesCatalogURL - the themes' catalog (an index.json built by app
// theme index from a list of the themes' repositories): the Appearance
// page's catalog and its updates. The Kosatka catalog by default;
// "off" (or THEMES_CATALOG_URL set empty) - no catalog.
ThemesCatalogURL string `yaml:"themes_catalog_url" env:"THEMES_CATALOG_URL" env-default:"https://kosatka-cms.github.io/themes/index.json"`
// TranslationsCatalogURL - the translations catalog (an index.json of
// the interface's languages to download, their files next to it): the
// Interface translations page's Languages tab, app install -language.
// The Kosatka catalog by default; "off" (or TRANSLATIONS_CATALOG_URL
// set empty) - no catalog.
TranslationsCatalogURL string `` /* 130-byte string literal not displayed */
// TemplatesDebug - HTML comments in the pages naming the template
// files that rendered them and the suggestions tried (like Twig debug,
// service.DefaultTemplateService.SetDebug); for a theme's author, not
// a live site.
TemplatesDebug bool `yaml:"templates_debug" env:"TEMPLATES_DEBUG"`
// Files - where public files (uploads) live and the URL path they are
// served at (see paths.SetPublicFiles).
Files FilesConfig `yaml:"files"`
// EngineDir - where the engine's own files are when several sites share
// one engine: <dir>/web/templates and <dir>/web/static; the site runs in
// its own directory, with its config, themes and files (see
// paths.SetEngineDir). Empty - the working directory's web/.
EngineDir string `yaml:"engine_dir" env:"ENGINE_DIR"`
// Content - the content's lifecycle.
Content ContentConfig `yaml:"content"`
}
Config - the site's configuration: the YAML file Load reads, with the environment variables (the env tags) over its values. Env - the environment, EnvProd (the default) or EnvLocal; Port - the port the site's HTTP server listens on.
func LoadPath ¶
LoadPath - the config at configPath, with the environment's values over the file's and the defaults that depend on the others.
func MustLoadPath ¶
MustLoadPath - LoadPath, a panic on a failure (the tests).
type ContentConfig ¶
type ContentConfig struct {
// TrashDays - how many days deleted content stays in the trash before
// it is deleted for good (service.NodeDeleteService.TrashJob); 0 -
// until the trash is emptied by hand.
TrashDays int `yaml:"trash_days" env:"CONTENT_TRASH_DAYS" env-default:"30"`
}
ContentConfig - the content's lifecycle.
type DBConfig ¶
type DBConfig struct {
// Driver - the database server: DriverMySQL (default) or DriverPostgres.
Driver string `yaml:"driver" env:"DB_DRIVER" env-default:"mysql"`
Host string `yaml:"host" env:"DB_HOST"`
// Scheme is the database name (yaml key "scheme" for backward compatibility).
Scheme string `yaml:"scheme" env:"DB_NAME"`
Username string `yaml:"username" env:"DB_USER"`
Password string `yaml:"password" env:"DB_PASSWORD"`
Port int `yaml:"port" env:"DB_PORT"`
MaxOpenConns int `yaml:"max_open_conns" env:"DB_MAX_OPEN_CONNS" env-default:"25"`
MaxIdleConns int `yaml:"max_idle_conns" env:"DB_MAX_IDLE_CONNS" env-default:"5"`
// ConnMaxLifetime / ConnMaxIdleTime - minutes before a pooled connection
// is recycled (before the server drops it) or closed when idle.
ConnMaxLifetime int `yaml:"conn_max_lifetime" env:"DB_CONN_MAX_LIFETIME" env-default:"5"`
ConnMaxIdleTime int `yaml:"conn_max_idle_time" env:"DB_CONN_MAX_IDLE_TIME" env-default:"5"`
// TLS - MySQL: go-sql-driver/mysql's tls=... (e.g. true, skip-verify,
// preferred), needed when the server uses require_secure_transport=ON
// (many managed MySQL hosts). PostgreSQL: the sslmode (disable,
// require, verify-full, …).
TLS string `yaml:"tls" env:"DB_TLS"`
// SQLMode - MySQL only: session sql_mode set on every connection (the server's
// global mode is left untouched). Strict by default, so over-long strings
// or missing NOT NULL values fail instead of being silently coerced.
// SQLModeServerDefault ("server") keeps the server's global mode.
SQLMode string `yaml:"sql_mode" env:"DB_SQL_MODE" env-default:"STRICT_TRANS_TABLES,ERROR_FOR_DIVISION_BY_ZERO,NO_ENGINE_SUBSTITUTION"`
}
DBConfig - the site database's connection: the server (Driver, Host, Port - the driver's usual one when 0), the database (Scheme), the account, the pool's sizes and connection lifetimes, TLS and MySQL's session mode.
func (DBConfig) DSN ¶
DSN builds the driver's DSN for this config (SQLDriver) - the single place every binary connecting to the site database uses.
func (DBConfig) Dialect ¶
Dialect - the database's SQL dialect name: DriverMySQL or DriverPostgres (the names ent's dialect and sqldialect use).
func (DBConfig) IsPostgres ¶
IsPostgres - the site database is PostgreSQL.
type EmailConfig ¶
type EmailConfig struct {
SMTPHost string `yaml:"smtp_host" env:"SMTP_HOST"`
SMTPPort int `yaml:"smtp_port" env:"SMTP_PORT" env-default:"587"`
SMTPUser string `yaml:"smtp_user" env:"SMTP_USER"`
SMTPPassword string `yaml:"smtp_password" env:"SMTP_PASSWORD"`
FromAddress string `yaml:"from_address" env:"EMAIL_FROM_ADDRESS"`
}
EmailConfig - the outgoing mail's SMTP server (host, port, account) and the sender's address: the server's settings win over the admin's. A module's way of sending is set by its own environment variables (service.MailTransportField.Env).
type FilesConfig ¶
type FilesConfig struct {
PublicDir string `yaml:"public_dir" env:"FILES_PUBLIC_DIR"`
PublicURL string `yaml:"public_url" env:"FILES_PUBLIC_URL"`
// PrivateDir - files never served as they are, only through the
// application with a permission check (e.g. files sent with forms).
// Empty - ./private next to the application.
PrivateDir string `yaml:"private_dir" env:"FILES_PRIVATE_DIR"`
// Storage - where the public files are kept: "local" (the default,
// PublicDir) or a storage driver the binary has (a package outside
// the engine registers it: modulekit.AddFileStorage), configured by
// its own section of files (e.g. files.s3) and environment.
Storage string `yaml:"storage" env:"FILES_STORAGE"`
// PrivateStorage - where the private files are kept: "local" (the
// default, PrivateDir) or a storage driver, like Storage.
PrivateStorage string `yaml:"private_storage" env:"FILES_PRIVATE_STORAGE"`
// Drivers - the other keys of files: the storage drivers' sections,
// read by the drivers (DecodeDriver).
Drivers map[string]any `yaml:",inline"`
}
FilesConfig - the public files directory and its URL path. Empty - the defaults, ./web/uploads at /uploads/. Content stores the files' URLs: change the URL path only on a new site.
func (FilesConfig) DecodeDriver ¶
func (c FilesConfig) DecodeDriver(section string, v any) error
DecodeDriver fills v from the section files.<section> of the config file (v's yaml tags), then from the environment (its env tags win, as for the engine's own settings): a storage driver's settings.
type GoogleOAuthConfig ¶
type GoogleOAuthConfig struct {
ClientID string `yaml:"client_id" env:"GOOGLE_OAUTH_CLIENT_ID"`
ClientSecret string `yaml:"client_secret" env:"GOOGLE_OAUTH_CLIENT_SECRET"`
}
GoogleOAuthConfig - the Google OAuth client's keys (oauth.google), used while the admin's social sign-in settings save none for Google.
func (GoogleOAuthConfig) Config ¶
func (c GoogleOAuthConfig) Config() OAuthProviderConfig
Config - the keys as an OAuthProviderConfig.
type OAuthConfig ¶
type OAuthConfig struct {
Google GoogleOAuthConfig `yaml:"google"`
VK VKOAuthConfig `yaml:"vk"`
Yandex YandexOAuthConfig `yaml:"yandex"`
}
OAuthConfig holds OAuth 2.0 client credentials per provider.
type OAuthProviderConfig ¶
OAuthProviderConfig is a normalized view of provider credentials.
func (OAuthProviderConfig) Enabled ¶
func (c OAuthProviderConfig) Enabled() bool
Enabled reports whether both keys are set: the provider can be used.
type RecaptchaConfig ¶
type RecaptchaConfig struct {
SiteKey string `yaml:"site_key" env:"RECAPTCHA_SITE_KEY"`
SecretKey string `yaml:"secret_key" env:"RECAPTCHA_SECRET_KEY"`
}
RecaptchaConfig enables Google reCAPTCHA v2 on auth forms when both keys are non-empty.
type SessionConfig ¶
type SessionConfig struct {
SecretKey string `yaml:"secret_key" env:"SESSION_SECRET_KEY"`
Secure bool `yaml:"secure" env:"SESSION_SECURE" env-default:"false"`
MaxAge int `yaml:"max_age" env-default:"604800"` // 7 days in seconds
}
SessionConfig - the session cookie: SecretKey - the key signing it (required with env "prod"; empty elsewhere - a random one per process), Secure - sent over HTTPS only, MaxAge - its lifetime in seconds.
type TimeoutConfig ¶
type TimeoutConfig struct {
// ServerRead / ServerWrite / ServerIdle - the HTTP server's read,
// write (the whole response) and keep-alive idle timeouts.
ServerRead int `yaml:"server_read" env:"TIMEOUT_SERVER_READ" env-default:"15"`
ServerWrite int `yaml:"server_write" env:"TIMEOUT_SERVER_WRITE" env-default:"15"`
ServerIdle int `yaml:"server_idle" env:"TIMEOUT_SERVER_IDLE" env-default:"60"`
// Shutdown - how long a stopping server waits for requests in flight.
Shutdown int `yaml:"shutdown" env:"TIMEOUT_SHUTDOWN" env-default:"30"`
// DatabaseQuery - a page's database work (BaseController.DBContext).
DatabaseQuery int `yaml:"database_query" env:"TIMEOUT_DATABASE_QUERY" env-default:"30"`
// CacheUpdate - one refresh of the in-memory caches (sidebar blocks…).
CacheUpdate int `yaml:"cache_update" env:"TIMEOUT_CACHE_UPDATE" env-default:"15"`
// HTTPRequest - calls to outside services (reCAPTCHA, Resend, the SMTP
// server).
HTTPRequest int `yaml:"http_request" env:"TIMEOUT_HTTP_REQUEST" env-default:"30"`
}
TimeoutConfig - how long things may take, in seconds (yaml "timeouts").
type VKOAuthConfig ¶
type VKOAuthConfig struct {
ClientID string `yaml:"client_id" env:"VK_OAUTH_CLIENT_ID"`
ClientSecret string `yaml:"client_secret" env:"VK_OAUTH_CLIENT_SECRET"`
}
VKOAuthConfig - the VK OAuth application's keys (oauth.vk), used while the admin's social sign-in settings save none for VK.
func (VKOAuthConfig) Config ¶
func (c VKOAuthConfig) Config() OAuthProviderConfig
Config - the keys as an OAuthProviderConfig.
type YandexOAuthConfig ¶
type YandexOAuthConfig struct {
ClientID string `yaml:"client_id" env:"YANDEX_OAUTH_CLIENT_ID"`
ClientSecret string `yaml:"client_secret" env:"YANDEX_OAUTH_CLIENT_SECRET"`
}
YandexOAuthConfig - the Yandex OAuth application's keys (oauth.yandex), used while the admin's social sign-in settings save none for Yandex.
func (YandexOAuthConfig) Config ¶
func (c YandexOAuthConfig) Config() OAuthProviderConfig
Config - the keys as an OAuthProviderConfig.