Reference22 min read
Configuration
Every field of collage.Config and its sub-structs, with its default and what validation checks.
An application is configured with one collage.Config value, handed to collage.New. Every field has a usable zero value, so a configuration only says what differs from the defaults:
app, err := collage.New(&collage.Config{
Template: collage.TemplateConfig{Root: "templates"},
})
New does three things with it, in order:
- Fills in defaults. It sets every zero-valued field that has a default. It changes the value you passed, so you can read back exactly what the application was built with.
- Validates. It checks the result and returns the first problem as an error — see Validation.
- Builds the application. A template root that does not exist, a template that does not parse, a plugin's
Configurefailing — each is reported here, not at the first request.
Passing nil is an error. A nil configuration is a mistake rather than a request for defaults, because the configuration says where your templates are.
A scaffolded project builds its configuration in newApp, in main.go. What changes between your machine and a server comes from the environment; the rest is written there:
main.go gets each field of collage.Config. Development mode, the public origin, the address the server listens on and the forgery key come from the environment, so one binary runs on your machine and on a server; the port's -port flag defaults to PORT, or 6060. The plugins, their configuration, the embedded templates and the disk cache are written in main.go and the files beside it. Locale, Logger, DevWatch, TrailingSlash and Observability are not set, so each keeps its default. collage.New receives the whole value.The fields and their defaults are in the tables below. A complete configuration shows the scaffold's code, and Example: one configuration for development and production what a production application adds to it.
Config
| Field | Type | Default | Meaning |
|---|---|---|---|
DevMode | bool | false | Development mode across the framework. |
DevWatch | []string | none | Extra directories whose changes reload a development page. |
Logger | *slog.Logger | chosen at startup | The logger the framework and plugins write through. |
Server | ServerConfig | The HTTP server. | |
BaseURL | string | none | The site's public origin, https://example.com, for the absolute URLs a render cannot know otherwise. |
Security | SecurityConfig | Request-forgery protection. | |
Template | TemplateConfig | Template loading and rendering. | |
Cache | CacheConfig | The page cache. | |
Locale | LocaleConfig | Which locales URLs carry. | |
TrailingSlash | bool | false | End every page's URL in /. |
Observability | ObservabilityConfig | Metrics and tracing. | |
Plugins | []Plugin | none | Plugins registered while the application is built. |
PluginConfig | map[string]json.RawMessage | none | Each plugin's own configuration, keyed by plugin name. |
DevMode
Turns on development mode:
- templates reloaded from disk before every render;
- pages that reload themselves in the browser;
- failed fragments shown on the page;
- the page cache never read from, and a disk cache replaced by memory;
- directories named in
DevWatchwatched; - the built-in error page naming the fragment where a failure started, leading with the cause — for a template, the file, line and column of the call that failed — and showing the full error chain.
It must be off in production — those diagnostics carry paths, hostnames and whatever else error messages contain.
DevMode is the one switch; nothing else turns development mode on. A plugin reads it with host.DevMode(). A scaffolded project sets it from COLLAGE_DEV=1, which collage dev sets for you.
DevWatch
Directories, besides the templates and the mounts, whose changes reload a development page — for content your application reads from disk itself, such as Markdown or JSON.
app, err := collage.New(&collage.Config{
DevMode: os.Getenv("COLLAGE_DEV") == "1",
DevWatch: []string{"content"},
// ...
})
A directory that does not exist is skipped rather than an error, because the same configuration runs wherever the binary is started. It is ignored outside development. Watching a directory only reloads the browser; reading the new content on the next render — rather than a copy loaded at startup — is up to your code.
Logger
nil, the default, lets the framework choose when it builds the application:
- On a terminal — and only when nothing has replaced slog's default handler — a compact handler meant for a person, one line per record with a coloured level marker.
- Anywhere else it is
slog.Default(), unchanged — except whereFORCE_COLORis set, ascollage devdoes for the program it runs on a colour terminal, andNO_COLORis not.
An application that called slog.SetDefault keeps its handler. Pass a logger to be certain, such as a JSON handler for logs a machine reads. New leaves this field nil.
Plugins and PluginConfig
Plugins are registered in order while New runs. A plugin that must act before templates are parsed — to add a template function or wrap mounts — has to arrive here rather than through app.RegisterPlugin.
PluginConfig holds each plugin's section as raw JSON. The framework reads no file: fill it however you like, or use collage.LoadPluginConfig("plugins-config.json"), which returns nil for a missing file, or Env.PluginConfig, which a scaffolded newApp calls: the file in the working directory when there is one, otherwise the copy embedded in the binary. A key that names no registered plugin stops the application from starting with ErrUnknownPluginConfig, and so does a key inside a section that the plugin does not know. See Configuring plugins.
TrailingSlash
Every page has one address, and TrailingSlash says whether it ends in /. On, /blog/hello/ is the page and /blog/hello redirects to it with a 301; off, which is the default, it is the other way round. Links built by name — pageURL, pageURLIn, localeURL, app.URL — come out in the chosen spelling, a locale's home included: /tr/ on, /tr off.
Turn it on for a site you export to a static host. The export writes a page as <path>/index.html, which a host serves at /blog/hello/ and reaches from /blog/hello only through a redirect — so with it off, every canonical link, sitemap entry and internal link points at a redirect.
It applies to pages. A document is a file and keeps its path as written, /sitemap.xml either way, and an action is always spelled without the slash. Each still has one address: /sitemap.xml/ redirects to it with a 301, and a POST to /login/ with a 308, so the body is sent again.
ServerConfig
| Field | Type | Default | Meaning |
|---|---|---|---|
Host | string | "localhost" | Address the server listens on. |
Port | int | 6060 | TCP port, 1–65535. |
ReadTimeout | time.Duration | 15s | How long reading a request may take. |
ReadHeaderTimeout | time.Duration | 0 | How long reading the request headers alone may take. Zero uses ReadTimeout. |
WriteTimeout | time.Duration | 30s | How long writing a response may take. |
IdleTimeout | time.Duration | 60s | How long a keep-alive connection may sit idle. |
ShutdownTimeout | time.Duration | 10s | How long graceful shutdown waits for in-flight requests. |
DrainDelay | time.Duration | 0 | How long the server keeps serving, keep-alives off, once a shutdown starts and before the port closes; ignored in development. See Deployment. |
MaxBodyBytes | int64 | 4 MiB | Bound on a request body when the action it routes to sets none — applied before middleware. |
TrustedProxies | []string | none | Addresses and CIDR ranges of the proxies in front of the server, whose X-Forwarded-For is believed, and, when the list is set, whose X-Forwarded-Proto is. |
Host defaults to localhost, which is unreachable from outside the machine — in a container, set it to 0.0.0.0.
A scaffolded project fills Host and Port from the HOST and PORT environment variables. Under collage dev those are a loopback address collage dev chose, and it listens on yours itself, so keep reading them from the environment; see CLI.
MaxBodyBytes is not filled in by New: zero means the built-in 4 MiB (4 << 20 bytes), applied when a request arrives, and a negative value means unbounded. An unbounded body is memory an anonymous caller chooses the size of, so choose that deliberately. An action can set its own bound with WithMaxBodyBytes; see Forms and actions.
TrustedProxies is what makes the client's address knowable behind a reverse proxy, where every request's RemoteAddr is the proxy's. Each entry is an address or a CIDR range ("10.0.0.0/8", "127.0.0.1"); one that is neither makes collage.New fail, naming it. Empty, the default, X-Forwarded-For is never read, so a client cannot forge it, and collage.ClientIP(r) is RemoteAddr's host:
Server: collage.ServerConfig{
TrustedProxies: []string{"10.0.0.0/8", "127.0.0.1"},
},
A request from a trusted proxy names its client in X-Forwarded-For, read from the right: the first address that is not a trusted proxy is the client, or the leftmost when every one is.
- An entry may carry a port (
9.9.9.9:4567,[2001:db8::1]:443) or brackets ([2001:db8::1]). - An entry that is not an address (
unknown), met before any untrusted one, leaves the client unknown:ClientIPis the zeronetip.Addr, never the proxy.
List every hop, a CDN's published ranges included, and only proxies you run or your platform's documented ranges. Trusting a range a client can send from lets that client name any address it likes; a range with zero bits (0.0.0.0/0, ::/0) trusts everyone, and collage.New logs a Warn for it.
The same list decides whose X-Forwarded-Proto marks the forgery cookie Secure; empty, that header is believed from anyone — right for a server only a proxy can reach. See Deployment.
SecurityConfig
| Field | Type | Default | Meaning |
|---|---|---|---|
CSRFKey | []byte | generated per process | Key that signs forgery tokens. Set it in production. |
CSRFCookieName | string | "collage_csrf" | Cookie a token is carried in. |
CSRFFieldName | string | "_csrf" | Form field a token is submitted in. |
CSRFHeaderName | string | "X-CSRF-Token" | Header a token may be submitted in instead. |
CSRFTrustedOrigins | []string | none | Other origins whose forms may post here, each scheme://host[:port]. |
DisableCSRF | bool | false | Turns forgery checking off for the whole application. |
CSRFTokenTTL | time.Duration | 12h | How long a forgery token stays valid after it is issued. Zero means the default; negative keeps a token valid for as long as its signature verifies. |
FrameOptions | string | "SAMEORIGIN" | X-Frame-Options sent on every response; "-" sends none, and any other value is sent as it is. |
DisableNoSniff | bool | false | Stops the X-Content-Type-Options: nosniff header sent on every response. |
Set CSRFKey in production. It should be at least 32 random bytes, kept with your other secrets and the same on every instance.
Left empty, a key is generated for each process: fine for a first run, wrong to deploy, because a generated key differs in every process: a token issued before a restart is refused after it, and one issued by an instance is refused by the next, so a form submitted across a restart, or to another instance of a fleet, fails. The application logs that it generated one — a warning outside development, at info level in it — and only when some action answers an unsafe method (POST, PUT, PATCH, DELETE) and is not exempted with WithoutCSRF, since only such an action ever verifies a token.
The key is not part of the disk cache's namespace, so the cache survives a new key; a cached page with a form in it, stored under the old one, is rendered again rather than served — see Caching. The scaffolded main.go reads it from COLLAGE_CSRF_KEY; openssl rand -hex 32 makes one.
CSRFTrustedOrigins names the origins, other than this one, whose forms may post here; every other origin is refused even with a valid token. See Forms and actions.
The name defaults above, and CSRFTokenTTL's 12h, are applied by the forgery guard, not by New, so the fields stay empty in your Config. CSRFFieldName renames the field on both sides: {{csrfToken}} writes the name the check reads, so forms need no change. Script that reads the token from the form — input[name="_csrf"] — has to use the new name.
CSRFTokenTTL is checked against the issue time signed into each token: a token past that age is refused, and a fresh one is minted for the next form.
DisableCSRF is for an application with no browser-submitted forms at all — an API behind its own authentication. With it set, {{csrfToken}} fails the render rather than rendering a form whose submission would mean nothing. To exempt one action instead, use WithoutCSRF on it.
TemplateConfig
| Field | Type | Default | Meaning |
|---|---|---|---|
FS | fs.FS | nil | Filesystem templates are loaded from; nil means disk. |
Root | string | "./templates" on disk | Directory templates are loaded from, stripped from every template name. |
Extension | string | ".html" | File extension of template files. |
Funcs | template.FuncMap | none | Extra template functions, merged over the built-ins. |
Timeout | time.Duration | 5s | Default data-handler timeout, and the default for every document handler that sets none. |
FS and Root
With FSnil, Root is a path on disk, relative to the working directory, and defaults to ./templates. With FS set, Root is a slash-separated directory inside it and is not defaulted — an empty Root means the root of FS itself.
Embedding is what lets a binary run from any directory:
//go:embed all:templates
var templates embed.FS
app, err := collage.New(&collage.Config{
Template: collage.TemplateConfig{FS: templates, Root: "templates"},
})
In development, an embedded set cannot change, so collage prefers the directory on disk when it is there. A Root that does not exist is ErrTemplateRootMissing from New, and a template under it that resolves outside it — through a symlink — is ErrTemplateEscapesRoot.
Funcs
Added to the built-in functions when the templates are parsed; an entry under a built-in name replaces that built-in, and an entry under a name a plugin added replaces the plugin's — one added with AddTemplateFunc or AddRenderFunc — and New logs each such name once. It must be set before New, because a template can only call a function that existed when it was parsed — a template calling an unknown name fails in New. The functions bound per render (slot, hoist, asset, stylesheet, csrfToken, pageURL, pageURLIn, localeURL, actionURL, fragmentURL, fragmentURLIn, withQuery) are rebound on every render, so overriding them has no effect, and New logs a warning naming each one given. See Template functions.
Timeout
The deadline for a data handler whose fragment sets none with WithTimeout. It is also the deadline of every document handler that sets none with DocumentBuilder.WithTimeout — so a slow feed raises its own budget there, rather than this one for every fragment and document. Like every timeout in collage it bounds the context the handler receives; a handler that never checks ctx.Done() can run past it.
CacheConfig
| Field | Type | Default | Meaning |
|---|---|---|---|
Enabled | bool | false | Master switch for the page cache. |
Store | Cache | nil | Your own cache implementation. |
Type | CacheType | CacheMemory when enabled | Built-in cache when Store is nil: collage.CacheMemory or collage.CacheDisk. |
DefaultTTL | time.Duration | 5m | Lifetime a built-in store gives an entry written with a TTL of zero or less. |
MaxEntries | int | 10000 | Cap on cache entries, memory and disk alike, and on the keys tracked under one tag; negative means unlimited entries. |
MaxBytes | int64 | 256 MiB memory, 1 GiB disk | Cap on the total size a built-in cache stores; negative means unlimited. A disk cache's memory tier holds 256 MiB, or MaxBytes when smaller. |
Dir | string | none | Where a disk cache stores entries, and, in Dir/data/, the collage.Cached values. Required for CacheDisk. One per instance: instances sharing it do not share a cache. |
Version | string | derived from the binary | Identifies the build a disk cache's entries belong to. |
WarmLimit | int | 1000 | Cap on the pages one invalidation re-renders in the background, newest first; negative turns warming off. |
Caching is off by default. With Enabled false nothing is cached, even with a Store set. Type defaults to collage.CacheMemory only when Enabled is true and Store is nil. An untyped literal, Type: "disk", still compiles; a string read from a variable needs converting: Type: collage.CacheType(v).
DefaultTTL is a built-in store's fallback, not a page's lifetime. The memory and disk caches give it to an entry written with a TTL of zero or less, and a negative value is refused by New. A page or a document never reaches it: Incremental(ttl) and its document equivalent refuse a TTL that is not positive, and a static page is kept until it is invalidated, so every entry the framework writes carries a TTL of its own. A custom Store is not given this value and applies its own default to a Set with a TTL of zero. collage.Cached takes a TTL of its own, and a zero there means the value never expires.
A Store replaces Type entirely, including in validation. Implement collage.Cache (Get, Set, InvalidateKey, Clear) to put pages in Redis or anywhere else; a store that also implements collage.TaggedCache (SetTagged, Invalidate) is handed each entry's tags on write and asked to invalidate by tag. A store that also implements collage.StaleCache (GetStale, MarkStaleKey, MarkStale) is asked to mark invalidated entries stale instead of removing them, and can then answer a failed re-render with the old page: see Caching. A store that implements collage.SharedCache, such as collage-redis, is shared by a fleet: pages and collage.Cached data live in it, and an invalidation on any instance reaches every one; see Caching. Leave the field unset rather than assigning a nil pointer of a concrete type, which is a non-nil interface that panics on the first lookup.
A disk cache outlives the process. Its entries live in a subdirectory of Dir named for a hash of Version, so a new build reads a different directory and finds nothing stale. Leave Version empty and it is a hash of the running executable, which changes exactly when the output might; set it — a commit, a release tag — when something outside the binary decides what pages look like. If the executable cannot be hashed, an in-memory cache is used instead, with a warning — and so when the directory cannot be created, a read-only filesystem say: collage.New warns and carries on with memory rather than failing. A write that fails once the application is running is logged, and the page is served uncached. In development a disk cache is never used: an in-memory one stands in for it.
A disk cache has memory in front of it. A hit is served from a memory tier, bounded by MaxEntries and by 256 MiB, or MaxBytes when that is smaller, and filled from the current build's directory at startup, newest first, so a restart serves its recent pages from memory at once. Each instance has its own tier, so give each instance its own Dir: with a shared one, an invalidation in one instance leaves the others serving their in-memory copy as fresh. See Caching.
Dir/data/ holds the collage.Cached values of a disk cache, so a restart comes up warm. Unlike the entries, they are not in a build's subdirectory, and they are not encrypted: see Caching.
MaxEntries also bounds the values collage.Cached keeps across requests.
MaxBytes bounds what a built-in cache weighs: zero picks the type's default, and a page larger than the whole cap is served but not stored. A custom Store ignores it. See Caching.
MaxEntries also bounds the framework's dependency tracker — the per-process index that maps a tag back to cache keys — per tag and in all, whatever the store is, a custom Store included. A negative MaxEntries keeps both caps at 10000.
Every distinct query string is a distinct key, and nothing removes a key from the tracker when the cache evicts or expires its entry, so without a cap a client could grow that index without limit. When a tag is at the cap, recording a new key drops its oldest key, and the cache entry for that key is removed with it: a key the tracker lets go of is one InvalidateTags could no longer reach, so it is never left cached to be served stale. The page renders again on its next request, as if the cache had evicted it. See Caching.
Zero for MaxEntries or MaxBytes means the default; only a negative value means unlimited. See Caching.
LocaleConfig
| Field | Type | Default | Meaning |
|---|---|---|---|
Default | string | "en" | Locale of a URL with no locale prefix. |
Supported | []string | [Default] | Every locale the application serves. |
PrefixDefault | bool | false | Give Default's pages a prefix too: /en/about. |
The URL is the only thing that selects a locale: /about is in Default, and /tr/hakkinda is in "tr". collage never picks one from Accept-Language or a cookie, because a URL that means different things to different readers is one caches, crawlers and shared links all get wrong.
/en/about, the default locale's own prefix, redirects permanently to /about — unless PrefixDefault is set, which makes /en/about the address and redirects /about to it; see Links and locales.
To negotiate, do it in middleware: redirect a Turkish browser to /tr, or render one URL per language and declare it with collage.Vary. See Links and locales.
ObservabilityConfig
| Field | Type | Default | Meaning |
|---|---|---|---|
Metrics | Metrics | no-op | Receives counters and timings. |
Tracer | Tracer | no-op | Starts spans around requests, renders and fragments. |
Both are interfaces you implement to bridge collage into your backend, and nil means a no-op. Metrics, Tracer and Span gain no methods within v1: a signal the framework reports later arrives as a separate, optional interface, found by type assertion. Embed collage.NoopMetrics, NoopTracer and NoopSpan in an implementation and define only the methods it needs, and it keeps compiling whatever is added.
type Metrics interface {
RenderDuration(ctx context.Context, page string, d time.Duration, cacheHit bool)
FragmentDuration(ctx context.Context, page, fragment string, d time.Duration, err error)
CacheEvent(ctx context.Context, event collage.CacheEvent, key string)
HTTPResponse(ctx context.Context, status int, path string, d time.Duration)
Invalidation(ctx context.Context, tags []string, keys int)
}
type Tracer interface {
StartSpan(ctx context.Context, name string) (context.Context, collage.Span)
}
type Span interface {
SetAttribute(key, value string)
RecordError(err error)
End()
}
A metrics bridge that counts responses and nothing else:
type responseCounter struct {
collage.NoopMetrics
responses atomic.Int64
}
func (m *responseCounter) HTTPResponse(ctx context.Context, status int, path string, d time.Duration) {
m.responses.Add(1)
}
CacheEvent is one of collage.CacheHit, CacheMiss, CacheSet, CacheEvict, CacheInvalidate, CacheCoalesced, CacheStale and CacheWarm. CacheCoalesced means a request was served by a render of the same key that was already running; CacheStale, that a collage.Cached value or a cached page was served stale, counted once per value or response served; CacheWarm, that a page or document an invalidation reached was rendered again in the background and stored, once per key.
HTTPResponse's path is the request's path, which a client chooses; label with collage.RouteInfo(ctx) instead, which is bounded. It is also called for a request refused by path normalisation — a dirty path's redirect, a path no route can match — with an empty path and RouteInfo kind "rejected", name "normalise". The collage.http span records http.method bucketed: the standard methods as themselves, anything else as OTHER. See Paths are cleaned first.
Validation
New returns the first of these it finds, after the defaults are filled in:
| Condition | Error |
|---|---|
Server.Port outside 1–65535 | ErrInvalidPort |
Cache.Enabled, no Store, and Type neither CacheMemory nor CacheDisk | ErrInvalidCacheType |
Cache.Enabled, no Store, TypeCacheDisk, and Cache.Dir empty | ErrEmptyCacheDir |
Locale.Default not in Locale.Supported | ErrLocaleDefaultNotSupported |
A negative Server.ReadTimeout, ReadHeaderTimeout, WriteTimeout, IdleTimeout, ShutdownTimeout, DrainDelay, Template.Timeout or Cache.DefaultTTL | ErrNegativeDuration |
BaseURL set and not a bare scheme://host[:port] | ErrInvalidOrigin |
The negative-duration error is one sentinel for all eight fields; the message names the one that failed, such as server.read_timeout. Because defaults are applied first, a zero port or an empty default locale never reaches validation from New — only a value you set explicitly can fail. Match these with errors.Is; the full list is in Errors.
Filling in defaults and validating are not exported on their own: New is the one place they run, so a test checks a configuration by calling it:
_, err := collage.New(&collage.Config{Server: collage.ServerConfig{Port: 70000}})
// errors.Is(err, collage.ErrInvalidPort)
Filling in defaults is idempotent: a configuration that already has them is left as it is.
A complete configuration
The configuration a scaffolded project starts from, with the parts that vary by environment read from it:
pluginConfig, err := env.PluginConfig(files)
if err != nil {
return nil, err
}
app, err := collage.New(&collage.Config{
DevMode: env.Dev,
BaseURL: os.Getenv("BASE_URL"),
Server: collage.ServerConfig{Host: env.Host, Port: env.Port},
Template: collage.TemplateConfig{
FS: files,
Root: "templates",
Extension: ".html",
},
Cache: collage.CacheConfig{
Enabled: true,
Type: collage.CacheDisk,
Dir: env.CacheDir,
DefaultTTL: 5 * time.Minute,
},
PluginConfig: pluginConfig,
Plugins: plugins(),
Security: collage.SecurityConfig{
CSRFKey: []byte(os.Getenv("COLLAGE_CSRF_KEY")),
},
})
env is the collage.Env that collage.Main hands the scaffolded newApp: Dev is COLLAGE_DEV=1, Host is HOST or localhost, Port is -port, PORT or 6060, and CacheDir is .cache. files is the project's embedded filesystem — the project directory itself in a development build — and plugins() comes from the plugins.go that collage plugin add and del manage. collage.Main loads .env before newApp runs, so os.Getenv sees it; see the CLI.
Example: one configuration for development and production
The team's task list — every member signs in, an admin may change any task of the team, a member only their own — runs under collage dev on a developer's machine and, in production, on two servers behind a load balancer. Its pages are in English and Turkish, and the team's admin panel, on a subdomain of its own, posts forms to it.
One binary serves both. Its newApp is the scaffold's, with the production settings added; what differs between the two is read from the environment or decided by env.Dev:
func newApp(env collage.Env) (*collage.App, error) {
pluginConfig, err := env.PluginConfig(files)
if err != nil {
return nil, err
}
cfg := &collage.Config{
DevMode: env.Dev,
BaseURL: os.Getenv("BASE_URL"), // collage dev's own address unless the environment file sets it
Server: collage.ServerConfig{
Host: env.Host,
Port: env.Port,
ReadHeaderTimeout: 5 * time.Second,
DrainDelay: 5 * time.Second, // ignored in development
},
Template: collage.TemplateConfig{
FS: files,
Root: "templates",
Extension: ".html",
},
Cache: collage.CacheConfig{
Enabled: true,
Type: collage.CacheDisk,
Dir: env.CacheDir,
DefaultTTL: 5 * time.Minute,
},
Locale: collage.LocaleConfig{
Default: "en",
Supported: []string{"en", "tr"},
},
PluginConfig: pluginConfig,
Plugins: plugins(),
Security: collage.SecurityConfig{
// Empty in development: a key is generated per process.
CSRFKey: []byte(os.Getenv("COLLAGE_CSRF_KEY")),
},
}
if !env.Dev {
// The load balancer in front of both servers, and the admin
// panel whose forms post here.
cfg.Server.TrustedProxies = []string{"10.0.1.10"}
cfg.Security.CSRFTrustedOrigins = []string{"https://admin.tasks.example.com"}
}
app, err := collage.New(cfg)
if err != nil {
return nil, err
}
// Routes and the static mount as scaffolded.
return app, nil
}
What each setting is in each place, and why:
| Setting | Development | Production | Why |
|---|---|---|---|
DevMode | on: collage dev sets COLLAGE_DEV=1 | off: the variable is unset | Development's error pages carry paths and error chains. A development server also answers only requests whose Host names this machine; see Deployment. |
Server.Host, Server.Port | the loopback address collage dev chose | HOST and PORT, or -port | collage dev listens on your address itself and passes requests on; see CLI. |
BaseURL | collage dev's own address, http://localhost:6060, unless the environment file sets BASE_URL | https://tasks.example.com from BASE_URL | Empty is not an error: a site that builds no absolute URL needs none. Set, it must be a bare origin, or New fails with ErrInvalidOrigin. |
Security.CSRFKey | empty: a key per process, logged at info level | at least 32 random bytes, the same on both servers | A generated key refuses every token issued before a restart, or by the other server. |
Security.CSRFTrustedOrigins | none | the admin panel's origin | Every other origin is refused, even with a valid token. |
Server.TrustedProxies | none | the load balancer | Without it, every client's address is the load balancer's. |
Server.DrainDelay | 5s, ignored | 5s | The load balancer stops sending traffic before the port closes. |
Server.ReadHeaderTimeout | 5s | 5s | A client sending headers a byte at a time is dropped early, while a body still has the whole ReadTimeout. |
Cache | the same lines: memory stands in, never read | a disk cache under .cache, one per server | Development shows the template you just edited. A disk cache comes up warm after a restart. |
Locale | en, tr | en, tr | The URL selects the locale, so nothing about it depends on where the binary runs. |
WriteTimeout, Template.Timeout | defaults, 30s and 5s | defaults, 30s and 5s | Keeping Template.Timeout well under WriteTimeout turns a slow upstream into a fragment's fallback rather than a connection closed halfway through the page; see Deployment. |
The development side needs nothing written down: collage dev sets COLLAGE_DEV, HOST and PORT. To keep a form open across the restarts collage dev makes when Go code changes, give development a key of its own in its environment file — .env, or .env.development when you keep one — never the production one; see CLI.
The production side is four variables — HOST, PORT, BASE_URL and COLLAGE_CSRF_KEY — plus any a plugin's KeyEnv names, set where the binary runs, or in a .env in its working directory, which collage.Main loads and the server's own variables override; see Deployment.