# Configuration

# Introduction

The Goyave framework lets you configure its core and your application. To configure your application, use the config.json file at your project's root. If you are using the template project, copy config.example.json to config.json. config.json should be ignored in your .gitignore file as it can differ from one developer to another. To avoid accidental commit or change to the default project's config, it is a good practice to ignore this file and define the project's default config in config.example.json.

If this config file misses some config entries, the default values will be used. All values from the framework's core are validated. That means that the application will not start if you provided an invalid value in your config (For example if the specified port is not a number).
You can register your own configuration entries for them to be validated too.
See the configuration reference for more details.

# Environment configuration

Most projects need different configuration values based on the environment. For example, you won't connect to the same database if you're in local development, in a testing environment inside continuous integration pipelines, or in production. Goyave supports multiple configurations and will pick the appropriate one depending on the environment variable GOYAVE_ENV.

Since v2.0.0, you can use custom environments.

GOYAVE_ENV Config file
test config.test.json
production config.production.json
custom_env config.custom_env.json
local / localhost / not set config.json

# Using the configuration

Before being able to use the config, import the config package:

import "github.com/System-Glitch/goyave/v2/config"

The configuration is loaded automatically when the server starts, but you can reload it manually if needed.

# config.Load

Parameters Return
error

Example:

config.Load()

# Getting a value

# config.Get

Get a generic config entry. You may need to type-assert it before being able to use it. You can do so safely as the config values and types are validated. Panics if the entry doesn't exist.

Parameters Return
key string interface{} or panic

Example:

config.Get("appName") // "goyave"

# config.GetString

Get a string config entry. Panics if the entry doesn't exist or is not a string.

Parameters Return
key string string or panic

Example:

config.GetString("protocol") // "http"

# config.GetBool

Get a bool config entry. Panics if the entry doesn't exist or is not a bool.

Parameters Return
key string bool or panic

Example:

config.GetBool("debug") // true

# config.Has

Check if a config entry exists.

Parameters Return
key string bool

Example:

config.Has("appName") // true

# Setting a value

You can set a config value at runtime with the config.Set(key, value) function. Bear in mind that this change temporary and will be lost after your application restarts or if the config is reloaded. This function is mainly used for testing purposes. Values set using this function are still being validated, and your application will panic if the validation doesn't pass.

# config.Set

Parameters Return
key string void or panic
value interface{}

Example:

config.Set("appName", "my awesome app")

# Custom config entries

The core of the framework contains default values covering most cases, but you can still add custom entries for your most specific needs to the config simply by appending a property to your application's config file. The custom properties are not validated, so you can use the data type you want.

# Validating custom entries

# config.Register

Register a config entry for validation.

If the entry identified by the given key is set or modified, its value will be validated according to the given kind. If the entry already exists, it will be revalidated.

This method doesn't allow to override existing validation. Once an entry is registered, its expected kind cannot be modified.

Parameters Return
key string void or panic
kind reflect.Kind

Example:

config.Register("pluginConfig", reflect.Struct)

# Configuration reference

Entry Type Accepted values Default Note
appName string any "goyave"
environment string any "localhost"
maintenance bool true, false false If true, start the server in maintenance mode. (Always return HTTP 503)
host string any "127.0.0.1"
domain string any "" Used for URL generation Leave empty to use IP instead.
port float64 any 8080
httpsPort float64 any 8081
protocol string "http", "https" "http" See the HTTPS section
tlsCert string any none Path to your TLS cert
tlsKey string any none Path to your TLS key
debug bool true, false true When activated, print stacktrace on error and sends error message in response. Disable this in production!
timeout float64 any 10 Timeout in seconds
maxUploadSize float64 any 10 Maximum size of the request, in MiB
defaultLanguage string any "en-US" See the Localization guide
dbConnection string "none", "mysql", "postgres", "sqlite3", "mssql" "none" See the Database guide
dbHost string any "127.0.0.1"
dbPort float64 any 3306
dbName string any "goyave"
dbUsername string any "root"
dbPassword string any "root"
dbOptions string any "charset=utf8&parseTime=true&loc=Local"
dbMaxOpenConnections float64 any 20
dbMaxIdleConnections float64 any 20
dbMaxLifetime float64 any 300 The maximum time (in seconds) a connection may be reused.
dbAutoMigrate bool true, false false When activated, migrate all registered models at startup
jwtExpiry float64 any 300 The number of seconds a generated JWT token is valid for. See the authentication guide.

NOTE

Numeric values are parsed as float64 even if they are supposed to be integers so it covers the potential use-case of floats in the config.

# Setting up HTTPS

Setting up HTTPS on your Goyave application is easy. First, turn protocol to https in the config. Then, add the tlsCert and tlsKey entries in the config. These two entries represent respectively the path to your TLS certificate and your TLS key.

Certbot example:

{
    ...
    "protocol": "https",
    "tlsCert": "/etc/letsencrypt/live/mydomain.com/cert.pem",
    "tlsKey": "/etc/letsencrypt/live/mydomain.com/privkey.pem",
    ...
}

Restart your server and you should now be able to connect securely to your Goyave application! All HTTP requests will automatically be redirected to HTTPS.