aah Application Configuration

The configuration syntax is used by aah framework is very similar to HOCON syntax. To learn more about configuration syntax.

aah configuration structure is very flexible it is called as aah.conf. You can override every config value in the environment profiles also external config file.

You can add your custom config values into app config. Also it can be overridden in the environment profiles.

Reference to Routes Config, Security Config, Log Config.

Table of Contents

Have a look at aahframework.org app configuration. It is moderate one, it gives an idea on how you can do it for your application.


Application name, non-whitespace is recommend.

Default value is basename of import path.

name = "mysampleapp"


A friendly description of application purpose.

desc = "aah framework web application"


Application type, typically either Web or API.

type = "api"


Since v0.9 Application instance name is used when you’re running aah application cluster. This value is used in the context based logging, it distinguishes your instance log from other instances.

Typically you can pass instance_name value via aah external config or Environment variable.

instance_name = $AAH_INSTANCE_NAME


Since v0.8 Configure file path of application PID file to be written. Ensure application has appropriate permission and directory exists.

Default value is <app-base-dir>/<app-binary-name>.pid

pid_file = "/path/to/pidfile.pid"

Section: server { … }

HTTP server configuration values.


Server address is used to bind against host address, IP address, UNIX socket.

Default value is empty string.

address = ""

# for unix socket
address = "unix:/tmp/aahframework.sock"


Server port number is used to bind on particular port number. For port 80 and 443, put empty string or actual value.

Default value is 8080

port = "8080"

# for 80
port = "80"
# OR 
port = ""

# for 443
port = "443"
# OR 
port = ""


Since v0.8 Header value written as Server HTTP header. If you do not want to include Server header, comment it out.

Default value is aah-go-server.

header = "aah-go-server"


HTTP server max header bytes size. It is mapped to http.Server.MaxHeaderBytes.

Default value is 1mb

max_header_bytes = "1mb"


HTTP server keep-alive option.

Default value is true

keep_alive = true

Section: server.timeout { … }

This section is used supply server timeout configuration values.


Server read timeout is mapped to http.Server.ReadTimeout. Valid time units are s -> seconds, m -> minutes.

Default value is 90s

read = "90s"


Server write timeout is mapped to http.Server.WriteTimeout. Valid time units are s -> seconds, m -> minutes.

Default value is 90s

write = "90s"


Server grace shutdown timeout. Used when app receive the SIGINT, SIGTERM and does graceful shutdown. Valid time units are s -> seconds, m -> minutes.

Default value is 60s

grace_shutdown = "60s"

Section: server.ssl { … }

HTTP server SSL/TLS configuration values. By default it is disabled.


To enable SSL/TLS on the aah go server.

Default value is false.

enable = true


HTTPS server certificate file. Path to the cert file. It is required value if server.ssl.enable = true.

Default value is empty string.

cert = ""


HTTPS server cert key file. Path to the key file. It is required value if server.ssl.enable = true.

Default value is empty string.

key = ""


Go lang by default enables the HTTP/2 on TLS. For some reason if your use case needs disabling HTTP/2; not to worry, aah framework covers it for you. Just set this config value to true.

Default value is false.

disable_http2 = true

Section: server.ssl.redirect_http { … }

Since v0.9 Redirect HTTP => HTTPS functionality does protocol switch, so it works with domain and subdomains.

For example:
   http://aahframework.org      => https://aahframework.org
   http://www.aahframework.org  => https://www.aahframework.org
   http://docs.aahframework.org => https://docs.aahframework.org


To enabling HTTP => HTTPS redirects.

Default is value is false.

enable = true


Port no. of HTTP requests to listen. For standard port 80 put empty string or a value.

It is required value, no default.

port = "8080"


Redirect code to be used when redirecting HTTP request.

Default value is 307.

code = 307

Section: server.ssl.lets_encrypt { … }


To enable Let’s Encrypt CA auto SSL/TLS certs on the aah go server.

Let’s Encrypt is a free, automated, and open certificate authority (CA), they provide free digital certificates in order to enable HTTPS (SSL/TLS) for websites to create a more secure and privacy-respecting Web.

Note: Let’s Encrypt does not provide certificates for localhost.

Default value is false. Don’t forget to enable server.ssl.enable = true.

enable = true


Host policy controls which domains the autocert will attempt to retrieve new certificates for. It does not affect cached certs. It is array of domain and sub-domain names.

It is required, no default value.

host_policy = ["example.org", "docs.example.org"]


Renew before optionally specifies how early certificates should be renewed before they expire.

Default value is 10 days.

renew_before = 10


Email optionally specifies a contact email address. This is used by CAs, such as Let’s Encrypt, to notify about problems with issued certificates. If the Client’s account key is already registered, Email is not used.

Default value is empty string.

email = "jeeva@myjeeva.com"


Force RSA makes the autocert generate certificates with 2048-bit RSA keys. If false, a default is used.

Default is EC-based keys using the P-256 curve.

force_rsa = false


Cache optionally stores and retrieves previously-obtained certificates autocert manager. By default certs will only be cached for the lifetime of the autocert manager.

Autocert manager passes the Cache certificates data encoded in PEM, with private/public parts combined in a single Cache.Put call, private key first.

Default value is empty string.

cache_dir = "/path/to/store/cache/certs"

Section: request { … }

Request configuration values.


Since v0.8 Max request body size for all incoming HTTP requests except MultipartForm. Also you can override this size for individual route on specific cases in routes.conf if need be.

Default value is 5mb.

max_body_size = "10mb"


Request Multi-part size is used for form parsing when request Content-Type is multipart/form-data.

Default value is 32mb.

multipart_size = "32mb"

Section: request.id { … }

aah framework encourages to have unique Request Id for each incoming request, it is helpful for traceability. If request already has X-Request-Id HTTP header then it does not generate one.

Global Unique Identifier (GUID) generate implementation is based on Mango DB ObjectId algorithm.

  • 4-byte value representing the seconds since the Unix epoch,
  • 3-byte machine identifier,
  • 2-byte process id, and
  • 3-byte counter, starting with a random value.


To enable/disable request ID generation.

Default value is true.

enable = true


HTTP header name for generated Request ID. If request already has HTTP header then it does not generate one.

Default value is X-Request-Id.

header = "X-Request-Id"

Section: request.content_negotiation { … }

Since v0.8 Content negotiation is used to validate what is being offered and accepted by server in-terms of request and response. Also known as Content-Type restrictions.


To enable/disable Content Negotiation for your application.

Default value is false.

enable = true


Accepted - Content-Type HTTP header RFC2616.

For example: Client sends Content-Type header as application/xml. However server only supports JSON payload as request body. Then server responds with 415 Unsupported Media Type.

Default value is empty list and disabled.

accepted = ["application/json", "text/json"]


Offered - Accept HTTP header RFC2616.

For example: Client sends Accept header as application/xml. However server only supports serving JSON i.e. application/json. Then server responds with 406 Not Acceptable.

Default value is empty list and disabled.

offered = ["application/json", "text/json"]

Section: request.auto_bind { … }

Auto Bind configuration used to bind request parameters to controller action parameters.


Priority is used to select the bind source priority.

P -> Path Parameter
F -> Form Parameter
Q -> Query Parameter

For example: Let’s say you have a controller action named OrderInfo and its has parameter called orderId. So framework tries to parse and bind based on the priority. The orderId present in Path and Form, framework parse and binds the value from Path.

Typically recommended to have unique names in the request parameter though :) If value is not found then it returns with default Go zero value.

Default value is PFQ.

priority = "PFQ"


Tag Name is used for bind values to struct exported fields.

Default value is bind.

tag_name = "bind"

Section: i18n { … }

Internationalization and Localization configuration values.


It is used as fallback value if framework is unable to determine the locale information from HTTP Request as per RFC7231 and lang Query parameter is not present.

Default value is en.

default = "en"

Section: i18n.param_name { … }

Overriding Request Locale Accept-Language header value via URL Path parameter or URL Query parameter.


Specify URL Path Parameter name i.e. /:lang/home.html, /:lang/aboutus.html, etc. For e.g.: /en/home.html, /en/aboutus.html, /zh-CN/home.html, /zh-CN/aboutus.html etc.

Default value is lang

path = "locale"


Specify URL Query Param name i.e ?lang=en, ?lang=zh-CN, etc.

Default value is lang

query = "locale"

Section: format { … }

Date, Time format values. These formats used to parse in the order they defined while Auto Parse and Bind into controller action parameters.

Any parse error result in 400 Bad Request.


time = [
  "2006-01-02 15:04:05",

Section: runtime { … }

aah application runtime configuration values used for debugging, object pooling, etc.

Section: runtime.debug { … }


Choose an appropriate buffer size for collecting all goroutines stack trace dump based on your case.

Default value is 2mb.

stack_buffer_size = "2mb"


Whether to collect all the Go routines details or not.

Default value is false.

all_goroutines = false


Whether to strip source src base path from file path.

Default value is false.

strip_src_base = true

Section: render { … }


aah framework identifies the Content-Type value automatically, when aah.Reply() builder Content-Type value is not set. It identifies in the order of:

  • Based on URL file extension, supported .html, .htm, .json, .js, .xml and .txt
  • Request Accept Header - Most Qualified one as per RFC7321
  • Config render.default value supported types are html, json, xml and text
  • Finally aah framework uses http.DetectContentType method

Default value is empty string.

default = "json"


Pretty print option is very helpful in dev environment profile. It is only applicable to JSON and XML Content-Type.

Default value is false.

pretty = true

Section: render.gzip { … }

Gzip compression configuration for HTTP response.


By default Gzip compression is enabled in aah framework, however framework ensures HTTP client does accepts Gzip response otherwise it won’t use the Gzip compression.

Tip: If you have `nginx` or `apache` web server enabled with gzip in-front of aah go server then set this value to `false`. There is not point in doing double compression.

Default value is true.

enable = true


Used to control Gzip compression levels. Valid levels are 1 = BestSpeed to 9 = BestCompression.

Default value is 5.

level = 3

Section: view { … }


Choosing view engine for aah application. You could implement on your own with very simple interface view.Enginer.

Default value is go.

engine = "go"


Choosing your own view file extension. It is used while find, filter and parse view files.

Default value is chosen based on view.engine, while creating a new app using command aah new.

ext = ".html"


Whether you need a case sensitive view file resolve or not.

Default value is false.

# for e.g.: "/views/pages/app/login.tmpl" == "/views/pages/App/Login.tmpl"
case_sensitive = false


To use custom Go template delimiters on view files.

Default value is {{.}}

delimiters = "{{.}}"


By default aah framework chooses the default app layout as master.html if you do not provide one. However you may have a need that certain pages without layout. So use this option to disable the default layout for HTML rendering.

Note: With this setting you can still use layouts, just provide layout name via Reply().HTMLlf or Reply().HTMLl methods

Default value is true. Since v0.6

default_layout = false

Section: env { … }

Application environment profiles, to override app config for respective environment. For e.g: dev, qa, prod etc.


Indicates active profile name for application configuration.

Default value is dev.

active = "dev"

include - This is for example purpose, you can use include at any levels

Including all the environment profile overrides from env directory within config directory.

include "./env/*.conf"