Skip to content
Unreleased: these pages follow the main branch. The latest release is v0.5.
Configuration reference

Configuration reference

Every key starts with its area’s prefix (DB_, CACHE_, QUEUE_…). The key that picks a backend is <AREA>_DRIVER in every area (DB_DRIVER, CACHE_DRIVER, MAIL_DRIVER, STORAGE_DRIVER), except AI_PROVIDER.

Note: doctor warns about keys in your .env that look like these settings but aren’t read (QUEUE_CONNECTION, MAIL_MAILER, FILESYSTEM_DISK…), and names the key to use. A setting’s name before v0.5 stops the app instead (Former names).

Framework settings

Read by anetos.New into anetos.AppConfig.

KeyTypeDefaultDescription
APP_NAMEstringanetosApplication name, added to every log line as app
APP_ENVdevelopment | testing | staging | productionproductionDeployment environment; also selects .env.<APP_ENV>
APP_URLURLemptyThe app’s public URL (https://example.com, no path), for links that leave the app: OAuth callbacks (social login), links in emails (mailer.URL)
APP_DEBUGboolfalseEnables debugging aids. Rejected when APP_ENV=production
APP_SHUTDOWN_TIMEOUTduration30sTotal graceful-shutdown budget: components first, then shutdown hooks. Hooks always keep the smaller of 5s and a fifth of it. Keep it at or below your platform’s grace period (Kubernetes default: 30s)
APP_PROCESS_TYPESlistemptyThe process types run starts when it isn’t given --only (web; worker,scheduler), for platforms that set a process’s environment rather than its command; --only wins. Empty: every component. Since v0.6
APP_KEYbase64:… (32 bytes)emptyEncrypts and authenticates session cookies. Required by sessions, which fail at startup without it. Generate one with go tool anetos key:generate. Keep it secret
APP_PREVIOUS_KEYSlist of keysemptyOld keys that still decrypt, so APP_KEY can be rotated without logging everyone out
APP_TIMEZONEIANA time zone (Asia/Dhaka)UTCThe app’s zone: the process’s local zone (so time.Now, logs and formatting agree on every machine), the zone of anetos.Now and the default of SCHEDULE_TIMEZONE. Times are stored in UTC whatever it is. Local isn’t allowed. See Times and dates
APP_LOCALElocale (en, bn, pt-BR)enThe default locale: of requests that ask for no supported one, and of code outside requests. Read by i18n.New
APP_FALLBACK_LOCALElocaleenWhere a locale’s missing messages come from, after its parents (bn-BD, then bn); the framework’s English messages come last
APP_LOCALESlist of localesAPP_LOCALE and every locale with a catalogThe locales requests can ask for. APP_LOCALE must be one of them
APP_LOCALE_STRATEGYnone | prefix | subdomainnoneWhere a request’s locale is in its URL: nowhere (the locale cookie, the session, the logged-in user’s preference, Accept-Language), a path prefix (/bn/about; the default locale has none), or a subdomain (bn.example.com; needs APP_URL). See Translations
LOG_LEVELdebug | info | warn | errorinfoMinimum log level
LOG_FORMATtext | json | emptyemptyLog format; empty means JSON in production, text elsewhere

APP_ENV defaults to production so that a missing setting fails safe (debug off, JSON logs). The keys have type anetos.Secret, which prints, logs and encodes as [redacted]; use string(cfg.Key) for the value.

Struct tags

Used by config.Bind and config.Get.

TagExampleMeaning
env:"KEY"env:"DB_PORT"Read the field from KEY
env:"KEY,required"env:"DB_URL,required"Error if KEY is missing or empty and there is no default
env:"-"Ignore the field
default:"value"default:"5432"Used when the key is missing or empty
prefix:"P_"prefix:"DB_"On a nested struct (or pointer to struct) without env: prepend P_ to its keys
was:"OLD"was:"DB_USERNAME"The key’s former name (with the same prefix), read when the key is unset; the app logs a warning and doctor lists it
was:"OLD,removed"was:"DB_CONNECTION,removed"A former name no longer read: when it is set and the key isn’t, binding fails with a *config.RenamedError naming the key (since v0.6)

Untagged nested structs are bound recursively, without a prefix unless one is given. Unexported fields are ignored.

Supported field types

Go typeAccepted values
stringAnything
booltrue/false, 1/0, t/f, yes/no, on/off (any case)
int, int8 … int64Base-10 integers within range
uint, uint8 … uint64Base-10 non-negative integers within range
float32, float64Decimal numbers
time.DurationGo durations: 300ms, 30s, 5m, 1h30m
[]T of the aboveComma-separated; blanks trimmed; empty items dropped
*T of the aboveAllocated only when a value is present
Types whose pointer implements encoding.TextUnmarshalerWhatever UnmarshalText accepts, e.g. slog.Level

Any other type is a binding error.

.env syntax

FormResult
KEY=valuevalue (trailing spaces trimmed)
KEY=value # commentvalue; a # preceded by a space starts a comment
KEY=a#ba#b
export KEY=valuevalue; the export prefix is ignored
KEY= or KEY= # commentempty (treated as unset when binding)
KEY="a\nb ${OTHER}"Double quotes: escapes \n \r \t \" \\ \$, ${VAR} expansion, may span lines
KEY='raw ${OTHER}'Single quotes: literal, may span lines
KEY=${OTHER}-xUnquoted values also expand ${VAR}
# …Comment line

${NAME} resolves with the same priority as the final configuration: the process environment first, then keys defined earlier in the same file, then lower layers (for .env.<APP_ENV>, that’s .env). So a reference always sees the value the application sees. Unknown names become empty; a malformed reference such as ${ or ${A:-default} is an error. $NAME without braces is not expanded. If a key repeats, the last value wins. A UTF-8 byte order mark and CRLF line endings are handled.

Load order

config.Load (called by anetos.New) layers sources, highest priority first:

  1. Process environment
  2. .env.<APP_ENV>: APP_ENV is taken from the process environment, else from .env
  3. .env

anetos.WithConfigDir(dir) changes where the files are read from, and anetos.WithSource(src) replaces the whole mechanism (useful in tests).

Every key of an area starts with its prefix (DB_, CACHE_, MAIL_…), and the key that picks a backend is <AREA>_DRIVER. A few keys keep the name a whole ecosystem uses: ANTHROPIC_API_KEY, OPENAI_API_KEY, GEMINI_API_KEY, REDIS_URL, and the hosting platforms’ PORT (when HTTP_ADDR isn’t set) and DATABASE_URL (see DB_URL). go run . doctor points at a key in a .env file that is another framework’s name for a setting (QUEUE_CONNECTION), a former name left beside its new one, or a typo of a setting.

Former names

Projects made before v0.5 used other names for these settings. Since v0.6 the former names are no longer read: when one is set and its new name isn’t, the service that reads it doesn’t start, and the error names the setting to use (DB_CONNECTION (Config.Driver): renamed DB_DRIVER). With both set, doctor says to remove the former one.

Former nameName
DB_CONNECTIONDB_DRIVER
DB_DATABASEDB_NAME
DB_USERNAMEDB_USER
MIGRATE_ON_RUNDB_MIGRATE_ON_START
MIGRATE_READINESSDB_MIGRATE_READINESS
SEARCH_LANGUAGEDB_SEARCH_LANGUAGE
SEARCH_RANKINGDB_SEARCH_RANKING
CACHE_STORECACHE_DRIVER
SESSION_LIFETIMESESSION_TTL
SESSION_MAX_LIFETIMESESSION_MAX_TTL
AUTH_REMEMBER_LIFETIMEAUTH_REMEMBER_TTL
QUEUE_POLLQUEUE_POLL_INTERVAL
LOCALE_URLAPP_LOCALE_STRATEGY

Vite

Read by vite.New into vite.Config (since v0.6; see Bundle JavaScript and CSS with Vite).

KeyTypeDefaultDescription
VITE_DEV_URLpath or URL ending with /, without a queryemptyWhen set, @vite.Tags loads the entries from Vite’s development server there instead of the build: /build/, which anetos dev sets and forwards to Vite, or, running Vite yourself, its own address with its base (http://localhost:5173/build/), with server.origin set to that address without the base (http://localhost:5173) in vite.config, for the URLs in the frontend’s CSS. Rejected when APP_ENV is production or staging

HTTP server

Read by web.NewServer (or web.LoadConfig) into web.Config.

KeyTypeDefaultDescription
HTTP_ADDRstring:8080, or :$PORT when the platform sets PORTListen address. 127.0.0.1:0 picks a free port (tests)
HTTP_READ_HEADER_TIMEOUTduration10sTime to read request headers (slowloris protection)
HTTP_READ_TIMEOUTduration30sTime to read the whole request
HTTP_WRITE_TIMEOUTduration30sTime to write the response
HTTP_IDLE_TIMEOUTduration2mKeep-alive idle time
HTTP_SHUTDOWN_GRACEduration15sOn shutdown, how long in-flight requests may finish before their contexts are canceled and connections closed. Capped at half of APP_SHUTDOWN_TIMEOUT, so later stages keep time to drain
HTTP_REQUEST_TIMEOUTduration30sDeadline on each request’s context; expiry gives 503. 0 disables
HTTP_MAX_BODYsize10MBMaximum request body (512KB, 10MB, 1GB; units are powers of 1024); larger gives 413. 0 disables
HTTP_TRUSTED_PROXIESlist of IPs/CIDRsemptyPeers whose X-Forwarded-For is trusted for the client IP (X-Real-IP isn’t read)
HTTP_CLIENT_IP_HEADERstringemptyA header a platform’s proxy sets to the client’s IP (do-connecting-ip, Fly-Client-IP), read instead of X-Forwarded-For: on connections from HTTP_TRUSTED_PROXIES when set, else from every connection (then the app must be reachable only through that proxy; doctor notes it). Without the header, the peer’s address. Since v0.6
HTTP_ACCESS_LOGbooltrueOne log line per request
HTTP_HEALTH_ROUTESbooltrueServe GET /health/live and GET /health/ready
HTTP_CORS_ORIGINSlistempty (CORS off)Allowed origins; * for any; https://*.example.com for subdomains
HTTP_CORS_METHODSlistGET,HEAD,POST,PUT,PATCH,DELETEAllowed methods for preflights
HTTP_CORS_HEADERSlistAccept,Authorization,Content-Type,X-Requested-With,X-Request-IDAllowed request headers
HTTP_CORS_EXPOSElistX-Request-ID,Location,Retry-After,X-RateLimit-Limit,X-RateLimit-RemainingResponse headers readable by browsers (Location and the rate limit’s)
HTTP_CORS_CREDENTIALSboolfalseAllow cookies; can’t be combined with *
HTTP_SPA_ORIGINSlistemptyThe origins of the app’s own SPAs (https://app.example.com, without a path), comma-separated: their requests are first-party (web.IsFirstParty, by Origin or Referer, or Sec-Fetch-Site on a listed host; not with an API token), allowed CORS with credentials and the X-XSRF-TOKEN header, and accepted by web.CSRF; make:auth’s API accounts log them in with a session cookie. Since v0.6
HTTP_CORS_MAX_AGEduration10mHow long browsers cache preflights

Streaming responses lift HTTP_REQUEST_TIMEOUT and HTTP_WRITE_TIMEOUT for themselves: c.EventStream() (server-sent events, and ai.SSE) does both; other streams use web.WithoutTimeout(ctx) for the request’s context and http.ResponseController’s SetWriteDeadline for the response. They should end when srv.Stopping() is closed, so shutdown doesn’t wait for the grace period.

HSTS (Strict-Transport-Security) is sent automatically when APP_ENV=production; serve production over HTTPS (usually at your proxy or load balancer).

Sessions

Read by session.New (or session.LoadConfig) into session.Config.

KeyTypeDefaultDescription
SESSION_COOKIEstringanetos_sessionCookie name. A Secure cookie without SESSION_DOMAIN and with path / gets the __Host- prefix. A name you give with __Host- or __Secure- must meet the browser’s rules for it
SESSION_TTLduration2hThe session ends after this long without a request (at least 1m)
SESSION_MAX_TTLduration168hThe session ends this long after it started or was regenerated (login), however active. 0 disables
SESSION_EXPIRE_ON_CLOSEboolfalseBrowser-session cookie: dropped when the browser closes
SESSION_DOMAINstringempty (this host only)Cookie domain; set it to share the session with subdomains
SESSION_PATHstring/Cookie path
SESSION_SECUREbooltrue, except development and testingSend the cookie over HTTPS only
SESSION_SAME_SITElax | strict | nonelaxCookie SameSite mode; none requires SESSION_SECURE=true
SESSION_DRIVERcookie | database | a driver’s name (redis)cookieWhere sessions are kept: the encrypted cookie, or a server-side store (the cookie then holds the encrypted session ID); redis needs redis.SessionDriver() passed to session.New
SESSION_TABLEstringsessionsThe database driver’s table; pass the same name to session.Migrations
SESSION_PREFIXstringAPP_NAME + :session:Starts the store keys of server-side sessions. anetostest sets one per test app

The cookie is always HttpOnly. Its content is encrypted with APP_KEY; with the cookie driver it holds the whole session, limited to about 4 KB. Server-side sessions are stored, encrypted, under keys starting with SESSION_PREFIX.

Database

Read by db.Connect (or db.LoadConfig(src, prefix), which reads the same keys with a prefix, e.g. ANALYTICS_DB_HOST) into db.Config.

KeyTypeDefaultDescription
DB_DRIVERsqlite | postgres | mysqlsqliteSelects one of the drivers passed to db.Connect
DB_URLstringemptyComplete connection string in the driver’s format; when set, the five keys below are ignored. Use it for TLS and driver options. Without it, DB_HOST and DB_NAME, and with DB_DRIVER unset or postgres, a postgres:// DATABASE_URL (a hosting platform’s) is used, with the postgres driver
DB_HOSTstring127.0.0.1Server host (PostgreSQL, MySQL)
DB_PORTintdriver default (5432, 3306)Server port
DB_NAMEstringempty; SQLite: database/app.dbDatabase name, or the SQLite file (:memory: for an in-memory database)
DB_USERstringemptyUser
DB_PASSWORDstringemptyPassword
DB_TLSverify | skip-verify | noneverify with DB_TLS_CA set or a remote host; none for a local host (localhost, loopback, Unix socket)TLS of the connection built from DB_HOST (PostgreSQL sslmode=verify-full/require/disable, MySQL tls=true/skip-verify/false). With DB_URL, set it in the URL instead (setting both is refused)
DB_TLS_CApath or PEM textemptyPEM file of the CAs that sign the server’s certificate, or their PEM text (starting with -----BEGIN; \n written as two characters is a line break; since v0.6), as a platform gives it in a variable, for verify when they aren’t the system’s; setting it means verify (also through a tunnel on localhost), and it is refused with skip-verify or none
DB_MAX_OPEN_CONNSint25Maximum open connections (in-memory SQLite always uses 1)
DB_MAX_IDLE_CONNSint25Maximum idle connections kept for reuse
DB_CONN_MAX_LIFETIMEduration30mConnections are replaced after this long
DB_CONN_MAX_IDLE_TIMEduration5mIdle connections are closed after this long
DB_LOG_QUERIESboolon when APP_ENV=developmentLog every query, with its arguments and duration, at debug level
DB_SLOW_QUERYduration500msLog queries taking at least this long as warnings (without arguments). 0 disables
DB_REPEATED_QUERIESint5 when APP_ENV is development or testing, off elsewhereWarn when an operation (a request, a job, a listener, a task) runs the same query this many times or more: an N+1. 0 disables; otherwise at least 2. See Find N+1 queries
DB_MIGRATE_ON_STARTboolfalseWith migrate.New: run the pending migrations when the app starts with run (the default command) or serve, before its components. For one instance on SQLite in a container; the Dockerfile of a SQLite project sets it
DB_MIGRATE_READINESSbooltrueWith migrate.New: the server isn’t ready (/health/ready answers 503, health:check exits 1) while the database has migrations the app hasn’t run, rechecked every 5 seconds. Turn it off where the migrations run after the new version starts and the platform waits for it to be ready
DB_ALLOW_LOCAL_TIMEZONEboolfalseAccept a database session time zone other than UTC (set in DB_URL), which the app otherwise refuses at boot so the database never writes local times next to the app’s UTC ones. For a legacy database whose times are local; the app still writes UTC

Search

KeyTypeDefaultDescription
DB_SEARCH_LANGUAGEsimple | a languagesimpleHow search matches words: simple as written, in any language; english (PostgreSQL, SQLite) also matches their other forms; on PostgreSQL any text search configuration (german, french…). MySQL has simple only. Search indexes are built for it: change it, then run search:reindex
DB_SEARCH_RANKINGdefault | bm25defaultOrder of search results: the database’s own ranking, or BM25 (SQLite; PostgreSQL 17+ with the pg_textsearch extension; not MySQL). PostgreSQL needs search:reindex after a change

The app refuses to start when the database can’t serve these settings, or when a search index was built for other ones (except for migrate… and search:reindex); see Search.

Driver specifics:

  • SQLite connections use WAL journaling, a 5s busy timeout, foreign keys and immediate transactions. The file’s directory is created if missing.
  • SQLite stores times as UTC text in the format of its own CURRENT_TIMESTAMP (2026-09-30 12:00:00.5), so column defaults and values written by the app compare correctly.
  • PostgreSQL sessions use the UTC time zone unless DB_URL sets timezone, which the app then refuses at boot (see DB_ALLOW_LOCAL_TIMEZONE).
  • MySQL connections always read times as UTC time.Time (parseTime=true, loc=UTC) and report matched rows for updates (clientFoundRows=true), also when DB_URL says otherwise; sessions use time_zone='+00:00' unless DB_URL sets it, which the app then refuses at boot (see DB_ALLOW_LOCAL_TIMEZONE).

Cache

Read by cache.New (or cache.LoadConfig) into cache.Config.

KeyTypeDefaultDescription
CACHE_DRIVERmemory | database | a driver’s name (redis)memorySelects the store; redis needs redis.CacheDriver() passed to cache.New
CACHE_PREFIXstringAPP_NAME + :cache:Starts every key, so apps (and other features in Redis) can share a store; cache:clear removes only these keys. anetostest sets one per test app
CACHE_TABLEstringcacheThe database store’s table; pass the same name to cache.Migrations

Queue

Read by queue.New (or queue.LoadConfig) into queue.Config. See Queues.

KeyTypeDefaultDescription
QUEUE_DRIVERsync | memory | database | a driver’s name (redis)syncWhere jobs are kept; sync runs each job when it is dispatched. redis needs redis.QueueDriver() passed to queue.New
QUEUE_DEFAULTqueue namedefaultThe queue of jobs dispatched without queue.OnQueue, and of workers without queue.Queues. Lower-case letters, digits and . _ : -, up to 100
QUEUE_TRIESint ≥ 13Attempts per job, unless its type sets queue.Tries
QUEUE_TIMEOUTduration1mHow long an attempt may run, unless its type sets queue.Timeout
QUEUE_BACKOFFduration10sThe wait before the first retry, doubling for each later one, unless the type sets queue.Backoff
QUEUE_BACKOFF_MAXduration10mCaps the doubling
QUEUE_POLL_INTERVALduration1sHow long an idle worker waits before looking for jobs again
QUEUE_TABLE, QUEUE_FAILED_TABLEstringjobs, failed_jobsThe database driver’s tables; pass the same names to queue.Migrations
QUEUE_PREFIXstringAPP_NAME + :queue:Starts the Redis driver’s keys (Redis 5 or later). In a Redis Cluster, put a hash tag in it ({blog}:queue:). anetostest sets one per test app

Pub/sub

Read by pubsub.New (or pubsub.LoadConfig) into pubsub.Config, and by the drivers. See Pub/sub listeners.

KeyTypeDefaultDescription
PUBSUB_DRIVERmemory | a driver’s name (redis, gcp)memoryThe broker; redis needs redis.PubSubDriver() and gcp needs gcppubsub.Driver() passed to pubsub.New
PUBSUB_PREFIXstringnoneStarts topic names in the broker (Redis keys, Google IDs). Topics are shared with the other services using the broker, so leave it empty unless you need to separate them (or, in a Redis Cluster, need a hash tag: {events}:). anetostest sets one per test app
PUBSUB_REDIS_MAXLENint ≥ 01000000About how many messages each Redis stream keeps; 0 for no limit
PUBSUB_GCP_PROJECTstringnone (required with gcp)The Google Cloud project’s ID
PUBSUB_GCP_CREATEboolfalseCreate missing Google topics and subscriptions (development, the emulator)

Scheduler

Read by schedule.New (or schedule.LoadConfig) into schedule.Config. See Scheduling.

KeyTypeDefaultDescription
SCHEDULE_TIMEZONEIANA time zone (Asia/Dhaka)APP_TIMEZONEThe time zone of schedules without .In(tz). Times that clock changes skip don’t run that day; times they repeat run twice (see Scheduling)

Mail

Read by mailer.New (or mailer.LoadConfig) into mailer.Config, and by the drivers. See Send email.

KeyTypeDefaultDescription
MAIL_DRIVERlog | smtp | memory | a driver’s name (postmark)logHow emails are sent: log writes them to the app’s log (a warning in production), memory keeps them (tests; anetostest sets it); postmark needs postmark.Driver() passed to mailer.New
MAIL_FROM_ADDRESSemail addressnoneThe sender of messages without one; sending fails without either
MAIL_FROM_NAMEstringAPP_NAMEThe sender’s name
MAIL_SMTP_URLURLsmtp://127.0.0.1:1025The SMTP server: smtp://user:pass@host:587 (STARTTLS, required unless the host is local) or smtps://…:465 (TLS); parameters tls=none, timeout (default 30s), local_name. See SMTP settings
MAIL_POSTMARK_TOKENstringnone (required with postmark)The Postmark server’s API token (POSTMARK_API_TEST checks requests without sending)
MAIL_POSTMARK_STREAMstringoutboundThe Postmark message stream

AI

Read by ai.New (or ai.LoadConfig) into ai.Config, and by the drivers. See Add AI to your app.

KeyTypeDefaultDescription
AI_PROVIDERanthropic | openai | openai-compatible | gemini | fake | another driver’s namenone (required)The provider that runs the models; its driver must be passed to ai.New (fake is built in: it answers with scripted replies and never calls a model, a warning in production; anetostest sets it)
AI_MODELstringnone (required by the drivers)The model calls use unless they set ai.Model, by the provider’s name for it
AI_MAX_TOKENSint ≥ 14096The longest answer, in tokens, unless a call sets ai.MaxTokens; a longer one is cut off
AI_TIMEOUTduration > 010mHow long each request to the model may take, unless a call sets ai.Timeout; for a stream, including the time the reader’s loop takes
AI_EMBEDDING_PROVIDERa driver’s nameAI_PROVIDERThe provider of embeddings (ai.Embed, ai.Embeddings), when AI_PROVIDER’s has none (anthropic): openai, gemini, openai-compatible or fake; its driver is passed to ai.New, and reads its own settings. anetostest clears it
AI_EMBEDDING_MODELstringnone; fake-embedding with the fakeThe embedding model, by the provider’s name for it (text-embedding-3-small, gemini-embedding-001); stored with each chunk, and searches use only its chunks. Required for embeddings, and with AI_EMBEDDING_PROVIDER
AI_QUEUE_TIMEOUTduration > 015mHow long a queued reply (conv.QueueReply) may take, all its requests and tool calls. Also how long the queue’s workers wait before taking back a job of any type whose worker died (the queue’s lease is its longest job timeout)
ANTHROPIC_API_KEYsecretnone (required with anthropic)The Anthropic API key
ANTHROPIC_BASE_URLURLAnthropic’sAnother URL for the API (a proxy, a gateway)
OPENAI_API_KEYsecretnone (required with openai)The OpenAI API key
OPENAI_BASE_URLURLOpenAI’sAnother URL for OpenAI’s API (a proxy, a gateway)
OPENAI_COMPATIBLE_URLURLnone (required with openai-compatible)The API URL of an OpenAI-compatible server, up to /v1: http://localhost:11434/v1 for Ollama
OPENAI_COMPATIBLE_KEYsecretnoneIts API key, if it needs one (then the URL must be https, or on this machine)
GEMINI_API_KEYsecretnone (required with gemini)The Gemini API key, from Google AI Studio
GEMINI_BASE_URLURLGoogle’sAnother URL for the Gemini API

The OpenAI and Anthropic SDKs also read their own variables from the process environment (OPENAI_ORG_ID, OPENAI_PROJECT_ID, ANTHROPIC_AUTH_TOKEN…): the OpenAI driver uses them, the Anthropic and compatible drivers don’t.

Storage

Read by storage.New (or storage.LoadConfig) into storage.Config for each disk, and by the drivers. The default disk reads STORAGE_*; a disk named in STORAGE_DISKS, say avatars, reads STORAGE_AVATARS_* (STORAGE_AVATARS_DRIVER, STORAGE_AVATARS_S3_BUCKET, …). See Store files.

KeyTypeDefaultDescription
STORAGE_DISKScomma-separated namesnoneMore disks: lower-case letters, digits and _, starting with a letter
STORAGE_DRIVERlocal | memory | a driver’s name (s3, gcs)localWhere the disk’s files are; s3 needs s3.Driver() passed to storage.New, gcs gcs.Driver(). Named disks default to the default disk’s
STORAGE_ROOTdirectorystorage/app (storage/<name> for a named disk)The local driver’s directory
STORAGE_URLURLnoneWhere the disk’s files are served: a CDN, a public bucket, or the route of the disk’s handler. Needed for URL, and for TemporaryURL on local disks
STORAGE_PUBLICboolfalseAnyone may read the files at STORAGE_URL, so URL works; otherwise only signed temporary URLs do
STORAGE_S3_BUCKETstringnone (required with s3)The bucket
STORAGE_S3_REGIONstringus-east-1The bucket’s region (auto for R2). Named disks take the default disk’s region, endpoint, keys and path style if they set none of them
STORAGE_S3_ENDPOINTURLAWSThe store’s URL, for S3-compatible stores (R2, MinIO, …). Named disks take the default disk’s region, endpoint, keys and path style if they set none of them
STORAGE_S3_ACCESS_KEY, STORAGE_S3_SECRET_KEYstringnoneThe credentials; without them, the AWS environment variables, shared credentials file or instance role. Named disks take the default disk’s region, endpoint, keys and path style if they set none of them
STORAGE_S3_PATH_STYLEboolfalseThe bucket in the URL’s path (MinIO). Named disks take the default disk’s region, endpoint, keys and path style if they set none of them
STORAGE_S3_PREFIXstring ending in /noneA prefix for the disk’s keys in the bucket (uploads/)
STORAGE_GCS_BUCKETstringnone (required with gcs)The Cloud Storage bucket
STORAGE_GCS_PREFIXstring ending in /noneA prefix for the disk’s objects in the bucket (uploads/)
STORAGE_GCS_CREDENTIALS_FILEpathnoneA service account key file (JSON); without it or STORAGE_GCS_CREDENTIALS, Application Default Credentials (the service’s account on Google Cloud, GOOGLE_APPLICATION_CREDENTIALS, gcloud). Named disks take the default disk’s credentials and signer if they set none of them
STORAGE_GCS_CREDENTIALSsecret (JSON)noneA service account key’s JSON, instead of a file. Both settings take service account keys only: other credentials go through GOOGLE_APPLICATION_CREDENTIALS
STORAGE_GCS_SIGNERemailthe credentials’ accountThe service account that signs temporary URLs through the IAM API when the credentials have no private key (an error with a key, which signs for its own account)
STORAGE_EMULATOR_HOSThost:portnoneRead by the Cloud Storage client: talk to an emulator (fake-gcs-server) without credentials

Redis

Read by redis.Connect (module drivers/redis, also used by redis.CacheDriver(), redis.SessionDriver(), redis.QueueDriver() and redis.PubSubDriver()) into redis.Config.

KeyTypeDefaultDescription
REDIS_URLURLredis://127.0.0.1:6379/0The server, with its user, password and database: redis://:[email protected]:6379/2; rediss:// for TLS. Options go in the query string (?dial_timeout=3s)

The server is pinged when the app boots, so the app and commands that boot it fail fast when Redis is unreachable.

Authentication

Read by auth.New (or auth.LoadConfig) into auth.Config.

KeyTypeDefaultDescription
AUTH_LOGIN_URLpath/loginWhere Require sends guests asking for a page
AUTH_HOME_URLpath/ (auth.WithDefaultHomeURL sets another; make:auth’s is /dashboard)The page for logged-in users: where logging in or registering leads when there’s no page they asked for, and where Guest sends them
AUTH_REMEMBER_TTLduration720hHow long “remember me” lasts
AUTH_THROTTLEint5Login attempts allowed per minute for one login, or one account, from one IP address (cleared by a success)
AUTH_THROTTLE_IPint50Failed logins allowed per minute from one IP address (IPv6: its /64), whatever the login
AUTH_RESET_TTLduration60mHow long a password-reset token works
AUTH_VERIFY_TTLduration24hHow long an email-verification token works
AUTH_REVERT_TTLduration168hHow long the link that undoes a change of email address works
AUTH_CHALLENGE_URLpath/two-factor-challengeWhere a login waiting for a two-factor code asks for it (social login sends users there)
AUTH_TWO_FACTOR_URLpath/two-factorWhere users turn two-factor authentication on and off (the admin links there)
AUTH_SETTINGS_URLpath/settingsThe account settings page (make:auth’s); the admin links the user’s name to it when the app has it
AUTH_CONFIRM_URLpath/confirm-passwordWhere RequireConfirmed sends users to confirm their password
AUTH_CONFIRM_TTLduration15mHow long a confirmed password holds
AUTH_CLIENT_URLURLnoneThe client app of an API (https://app.example.com: http or https, no query): where emailed links lead (Auth.ClientLink); make:auth in an API project sets it, and its setupAuth refuses to boot without it in production and staging

The remember-me cookie is HttpOnly, SameSite=Lax and Secure like the session cookie; a Secure one is named __Host-anetos_remember.

Audit log

Read by audit.New into audit.Config. See Keep an audit log.

KeyTypeDefaultDescription
AUDIT_IPnone, masked, fullnoneWhether entries keep the client’s IP address: not at all, masked (IPv4 to its /24, IPv6 to its /48), or whole
AUDIT_BULK_MAX_VALUESint10000How many rows’ values a bulk entry keeps (every row’s key is kept), set when a model is tracked
AUDIT_RETENTION_DAYSint0How long audit:prune and audit.Prune keep entries; 0 keeps them forever

Admin

Read by admin.New into admin.Config (module anetos.dev/anetos/admin). See Add an admin panel.

KeyTypeDefaultDescription
ADMIN_PATHstring/adminWhere the admin is mounted; starts with /. With ADMIN_HOST, the admin is at that host’s root unless this is set; / needs ADMIN_HOST
ADMIN_HOSTstringemptyA host the admin answers on alone (admin.example.com, on any port; a port given here goes into its URLs); empty for every host
ADMIN_TITLEstringAPP_NAMEThe admin’s name in its pages (overrides admin.WithDefaultTitle)
ADMIN_PER_PAGEint25How many records a list shows, 1 to 500 (a resource’s PerPage overrides it)
ADMIN_CONFIRMbooltrueAsk for the password again (AUTH_CONFIRM_TTL) before dangerous actions: deleting, disabling, roles and permissions, impersonating a user, forgetting every failed job, actions marked Danger
ADMIN_TWO_FACTORoptional, requiredoptionalrequired lets in only users with two-factor authentication on; the others are told to turn it on (AUTH_TWO_FACTOR_URL)
ADMIN_ALLOW_IPSlistemptyAddresses or networks (10.0.0.0/8), comma-separated, the admin answers; others get 404. The client’s address is read behind trusted proxies only (HTTP_TRUSTED_PROXIES). Empty for every address

Social login

Read by social.New and social.Configured, for each provider name (GOOGLE, GITHUB, or the upper-cased name given to social.OIDC, with - as _).

KeyTypeDefaultDescription
SOCIAL_<NAME>_CLIENT_IDstringemptyThe client ID of the app registered with the provider
SOCIAL_<NAME>_CLIENT_SECRETstringemptyIts client secret

Callback URLs are APP_URL followed by /auth/<name>/callback (social.WithCallbackPath changes the path).

Plugins

Each plugin’s settings start with its name in capitals (STRIPE_…), and are read by ext.Load into the plugin’s own settings struct. go run . plugin:env prints them with their defaults; anetos add adds them to .env.example. Missing or invalid ones stop the app from booting, with an error naming them. See Use plugins.

postmark

Read by the plugin of plugins/postmark (its mail transport reads MAIL_POSTMARK_*: Mail).

KeyTypeDefaultDescription
POSTMARK_WEBHOOK_USERstringemptyThe user name of the webhook’s basic auth, set in the webhook’s URL in Postmark (https://USER:[email protected]/postmark/webhook). Without it or the password, the webhook refuses every request (401)
POSTMARK_WEBHOOK_PASSWORDsecretemptyThe webhook’s password