go-admingo-admin
  • Guide
  • Development
    • Advanced
    • Commands
  • Advanced
  • Help
  • GitHub
  • Changelog
⌘ K
Config Reference
Sharding by Business
Multi-Tenancy
Last updated:
Open-source MIT Licensed | Copyright © 2020-present
Powered by go-admin-team
‌
‌
‌
‌

Config Reference

This page walks through every available setting in config/settings.yml, block by block.

INFO

This page is written against go-admin v2.4.0 and the go-admin-core version it depends on. The repository also ships two reference files: config/settings.full.yml (a more complete example) and config/settings.sqlite.yml (a SQLite example).

Everything lives under the top-level settings key:

yml
settings:
  application: ...
  ssl: ...
  logger: ...
  jwt: ...
  database: ...
  gen: ...
  cache: ...
  queue: ...
  extend: ...

The config file is specified at startup with -c; without it, config/settings.yml is read by default:

sh
$ ./go-admin server -c config/settings.yml

application

The service's own runtime parameters.

FieldTypeDescription
modestringRun mode: dev / test / prod / demo — see below
hoststringListen address, defaults to 0.0.0.0
portintListen port
namestringService name
readtimeoutintHTTP read timeout, in seconds
writertimeoutintHTTP write timeout, in seconds
enabledpboolData-permission switch; when off, data is no longer filtered by department

What mode Actually Does

mode isn't just a label — it changes authorization and routing behavior, so set it correctly per environment:

ValueBehavior
devLogin skips captcha verification; the JWT lifetime is forced to 876,010 hours (about 100 years) — jwt.timeout has no effect
demoBlocks every write operation, allowing only GET / OPTIONS and the login/logout endpoints — meant for a public demo site
prodGin switches to ReleaseMode; the Swagger route, the / homepage, and the form-generator static directory aren't registered
testNo dedicated branch in the code — behaves the same as "not dev, not prod, not demo"

WARNING

Production must set mode: prod.

Accidentally deploying with dev still set causes two problems at once: login skips captcha verification, and issued tokens essentially never expire.

ssl

FieldTypeDescription
enableboolHTTPS switch
domainstringThe domain HTTPS serves
keystringSSL certificate key
pemstringSSL certificate path

logger

FieldTypeDescription
pathstringLog file directory
levelstringLog level: trace / debug / info / warn / error / fatal
stdoutstringConsole log switch — any non-empty value sends logs to the console instead of a file
enableddbboolDatabase log switch — prints SQL when enabled
typestringLogger component type
capuintLog channel capacity

WARNING

level: trace prints a large volume of logs — for production, info or higher is recommended.

jwt

FieldTypeDescription
secretstringThe token signing secret
timeoutint64Token lifetime, in seconds

WARNING

secret defaults to go-admin — it must be changed before going live, or anyone can forge a valid token.

Also note: under mode: dev, timeout has no effect (see the application section above).

database

FieldTypeDescription
driverstringDatabase type: mysql / postgres / sqlite3 / sqlserver
sourcestringConnection string
maxIdleConnsintMax idle connections, applied when greater than 0
maxOpenConnsintMax open connections, applied when greater than 0
connMaxIdleTimeintMax connection idle time, in seconds, applied when greater than 0
connMaxLifeTimeintMax connection lifetime, in seconds, applied when greater than 0
registerslistRead/write splitting and sharding config — see Sharding by Business

The source format for each database:

yml
# MySQL
source: user:password@tcp(127.0.0.1:3306)/dbname?charset=utf8&parseTime=True&loc=Local&timeout=1000ms


# PostgreSQL
source: host=myhost port=myport user=gorm dbname=gorm password=mypassword


# SQLite3 (requires building with -tags=sqlite3,json1)
source: sqlite3.db


# SQL Server
source: sqlserver://username:password@address?database=dbname

When the four connection-pool fields are left unset or set to 0, the corresponding setter is never called, and GORM and the database driver fall back to their own defaults.

databases

Under multi-tenancy, databases are selected by domain — see Multi-Tenancy for how to configure it. When databases isn't configured, the system automatically registers database's config under the key *.

gen

Config for the code generator.

FieldTypeDescription
dbnamestringThe database name the generator reads from
frontpathstringWhere generated frontend code is written — must point at the src folder, as a relative path

cache

Selection order is redis first, memory only if redis isn't configured:

FieldTypeDescription
memoryanyIn-memory cache — leave empty for a single-instance deployment
redis.addrstringRedis address, e.g. 127.0.0.1:6379
redis.passwordstringRedis password
redis.dbintRedis logical database index
redis.pool_sizeintConnection pool size — uses the driver's default if unset

WARNING

A misconfigured redis section makes the service fail to start — it does not silently fall back to the in-memory cache. The connection is verified at startup (a 5-second timeout by default); a wrong address or password causes the service to exit with an error.

If you're running multiple instances and need a shared cache (captchas, tokens, and anything else that depends on it), redis must be configured — for a single instance, leaving memory empty works fine on its own.

queue

Same rule: redis first, memory only if redis isn't configured:

FieldTypeDescription
memory.poolSizeuintGoroutine pool size for the in-memory queue
redis.addrstringRedis address
redis.passwordstringRedis password
redis.groupstringConsumer group — every instance of the same app must use the same value
redis.key_prefixstringPrepended to the stream key, for isolating multiple apps sharing one Redis instance
redis.max_attemptsintMax redelivery attempts for a message that fails

The redis option is built on Redis Streams — messages persist and are visible across instances. As with cache, a misconfiguration makes the service fail to start rather than silently degrading.

Full usage and code examples are in Cache and Queue.

extend

Custom configuration. Define a struct matching your config in config/extend.go, then read it via config.ExtConfig.

yml
extend:
  amap:
    key: your-key
go
package config


var ExtConfig Extend


type Extend struct {
	AMap AMap
}


type AMap struct {
	Key string
}

Read it like this:

go
config.ExtConfig.AMap.Key

Fields That Aren't Parsed

The locker block that appears in config/settings.yml has no corresponding field in the current version of core's config struct — anything written there is never read.

WARNING

Where to get help:

If anything in this guide is unclear, please open an issue.