Config File Reference
Detailed reference for the most important FiveNet configuration options.
This page follows
config.example.yaml and focuses on the settings most deployments will need to review.Config File Location
By default, FiveNet looks for config.yaml in this order:
.- The current working directory/config- Commonly used by containerized deployments
Use the example configuration file as the source of truth for comments, defaults, and all available options.
Required Options
These are the settings you should treat as mandatory for a working installation.
http.publicURL
string required
The public URL of your FiveNet instance, for example
https://fivenet.example.com.http.sessions.cookieSecret
string required
Random secret used for session cookies. Generate it once and keep it stable. Use at least 24 characters.
http.sessions.domain
string required
The public domain or subdomain FiveNet runs on, for example
fivenet.example.com.database.dsn
string required
MySQL or MariaDB connection string.Keep the parameters after
DB_USER:DB_PASS@tcp(DB_HOST:DB_PORT)/DB_NAME?collation=utf8mb4_unicode_ci&parseTime=True&loc=Europe%2FBerlin
?. In most cases, only the loc= timezone part should be changed.nats.url
string required
NATS connection URL, including credentials if needed, for example
nats://USER:PASSWORD@localhost:4222.JetStream must be enabled on the NATS server.jwt.secret
string required
Secret used to sign user tokens. Generate it once and keep it stable. Use at least 24 characters.
auth.configAdminGroups
string[]
Groups that should receive config admin access in FiveNet.
sync.enabled + sync.apiTokens
boolean + string[]
Enable the Sync API and provide at least one token. This is required for the FiveNet plugin and DBSync.
Core Settings
mode
string
Controls whether FiveNet runs in
debug or release mode.logLevel
string
Default log level for the application.
log
logToStderr
boolean
Send logs to stderr instead of stdout.
logToFile
boolean
Write logs to a file instead of stdout.
file
path
string
Path to the log file.
rotation
maxSize
number
Maximum log file size in megabytes before rotation.
maxBackups
number
Maximum number of rotated log files to keep.
maxAge
number
Maximum number of days to keep rotated log files.
compress
boolean
Compress rotated log files with gzip.
rotationInterval
string
Interval for log rotation, for example
24h.levelOverrides
map[string]string
Per-subsystem log level overrides such as
kvstore, locks, cron, and perms.secret
string
App-wide encryption secret used to protect stored data. Keep this separate from
jwt.secret.ignoreRequirements
boolean
Skip database and NATS connectivity checks during startup. Use only when those services are intentionally unavailable.
jwt
secret
string
JWT signing secret. Keep it separate from the root
secret value.HTTP
http
listen
string
Main HTTP listen address.
adminListen
string
Admin listen address for metrics and debug endpoints. Bind this to localhost or disable it if you do not need it.
publicURL
string required
Canonical public base URL for your FiveNet instance, including scheme and host.
origins
string[] required
Allowed browser origins for the frontend and API. Add each origin explicitly.
trustedProxies
string[] required
Trusted reverse proxy IPs or CIDR ranges that may forward client headers.
sessions
required
cookieSecret
string required
Secret used to sign and encrypt session cookies.
domain
string required
Cookie domain for session cookies.
Database
database
dsn
string required
MySQL or MariaDB DSN. The example file includes the recommended
collation and loc settings.maxOpenConns
number
Maximum number of open database connections.
maxIdleConns
number
Maximum number of idle database connections.
connMaxIdleTime
string
Maximum amount of time a connection may remain idle.
connMaxLifetime
string
Maximum lifetime of a connection.
disableLocking
boolean
Disable database locking behavior.
skipMigrations
boolean
Skip database migrations on startup.
custom
columns
map
Override database column names. Set a column to
"-" to disable it.conditions
map
Additional database condition overrides.
NATS
nats
url
string
NATS connection URL, including credentials if needed.
replicas
number
Number of replicas to use for streams and key-value stores.
Storage
storage
type
'filesystem' | 's3'
Select the storage backend to use for uploads.
filesystem
path
string
Local filesystem path used for storage.
prefix
string
Optional key prefix within the filesystem store.
s3
endpoint
string
S3-compatible endpoint URL.
region
string
S3 region.
accessKeyID
string
S3 access key ID.
secretAccessKey
string
S3 secret access key.
useSSL
boolean
Use HTTPS for S3 requests.
bucketName
string
Target S3 bucket.
prefix
string
Optional key prefix within the bucket.
retries
number
Number of retry attempts for S3 operations.
checkOnStartup
boolean
Check the S3 configuration on startup.
metricsEnabled
boolean
Enable storage metrics.
metricsInterval
string
Interval for collecting storage metrics.
Image Proxy
imageProxy
options
allowHosts
string[]
Hosts allowed for proxied image requests.
denyHosts
string[]
Hosts denied for proxied image requests. Deny rules take precedence.
minimumCacheDuration
string
Minimum cache duration for image responses.
Audit
audit
retentionDays
number
Number of days to retain audit entries before cleanup.
OAuth2
oauth2
providers
array
List of OAuth2 providers.
name
string
Internal provider name used in config and callback routes.
label
string
Display label shown on the login button.
homepage
string
Provider homepage shown in the UI.
icon
string
Iconify icon name or image URL shown on the login button.
defaultAvatar
string
Optional fallback avatar URL.
type
string
Provider type, for example
discord or generic.redirectURL
string
Callback URL registered with the OAuth2 provider.
clientID
string
OAuth2 client ID.
clientSecret
string
OAuth2 client secret.
scopes
string[]
Requested OAuth2 or OpenID scopes.
endpoints
authURL
string
Authorization endpoint.
tokenURL
string
Token exchange endpoint.
userInfoURL
string
User info endpoint.
mapping
id
string
Claim or field used as the unique user identifier.
username
string
Claim or field used as the username.
avatar
string
Claim or field used as the avatar URL.
Files and Auth
postalsFile
string
Path to the
postals.json data file used by FiveNet.auth
jobAdminGroups
string[]
Groups that receive job admin superuser access.
jobAdminUsers
string[]
Users that receive job admin superuser access regardless of group membership.
configAdminGroups
string[]
Groups that receive config admin superuser access.
configAdminUsers
string[]
Users that receive config admin superuser access regardless of group membership.
Dispatch Center
dispatchCenter
type
string
Dispatch system type to convert into FiveNet dispatches.
convertJobs
string[]
Jobs to convert from dispatches into FiveNet dispatches.
Discord
discord
enabled
boolean
Enable the Discord integration.
dryRun
boolean
Run Discord actions without changing roles or sending messages.
token
string
Discord bot token.
sync
boolean
Enable Discord synchronization activity.
groupSync
enabled
boolean
Enable syncing server groups to Discord roles.
mapping
map
Map group names to Discord role settings.
userInfoSync
enabled
boolean
Enable syncing job, grade, and qualification data to Discord roles.
gradeRoleFormat
string
Format string for grade roles.
employeeRoleFormat
string
Format string for employee roles.
unemployedRoleName
string
Role name used for unemployed users.
jobsAbsceneRoleName
string
Role name used for absent users.
qualifications
enabled
boolean
Enable syncing qualifications to Discord roles.
commands
enabled
boolean
Enable Discord command registration.
absent
boolean
Enable the
absent command.fivenet
boolean
Enable the
fivenet command.help
boolean
Enable the
help command.sync
boolean
Enable the
sync command.calendarReminders
boolean
Send calendar reminders in Discord.
Game and Sync
game
startJobGrade
number
First job grade number or ID used by the server.
cleanupRolesForMissingJobs
boolean
Remove Discord roles for jobs that no longer exist.
sync
enabled
boolean
Enable or disable the sync API endpoint.
apiTokens
string[]
API tokens accepted for sync requests.
Updates, Icons, and Tracing
updateCheck
enabled
boolean
Check for updates on a schedule.
interval
string
Interval between update checks.
icons
proxy
boolean
Proxy Iconify requests through the backend instead of using local icon sets.
apiUrl
string
Iconify API URL used when proxy mode is enabled.
path
string
Local icon set directory used when proxy mode is disabled.
otlp
enabled
boolean
Enable OTLP tracing export.
type
'stdout' | 'otlptracegrpc' | 'otlptracehttp'
Export mode for the OTLP client.
url
string
OTLP collector endpoint URL.
insecure
boolean
Allow insecure OTLP transport.
timeout
string
Timeout for OTLP requests.
environment
string
Environment label attached to traces.
ratio
float
Sampling ratio for traces.
attributes
array
Additional span or resource attributes.
headers
map[string]string
Extra headers sent to the OTLP endpoint.
compression
string
Compression used for OTLP exports.
frontend
url
string
Frontend trace endpoint. Leave empty to disable frontend instrumentation.
headers
map[string]string
Extra headers sent from the frontend tracing client.
Notes
- Keep
secret,jwt.secret, session secrets, and sync tokens stable after deployment unless you intentionally want to invalidate existing sessions or access. - Use the example file for comments and the complete set of options.