github.com/System-Glitch/goyave/v2@v2.10.3-0.20200819142921-51011e75d504/docs/guide/configuration.html (about) 1 <!DOCTYPE html> 2 <html lang="en-US"> 3 <head> 4 <meta charset="utf-8"> 5 <meta name="viewport" content="width=device-width,initial-scale=1"> 6 <title>Configuration | Goyave</title> 7 <meta name="generator" content="VuePress 1.5.3"> 8 <link rel="icon" type="image/png" sizes="16x16" href="/goyave/goyave_16.png"> 9 <link rel="icon" type="image/png" sizes="32x32" href="/goyave/goyave_32.png"> 10 <link rel="icon" type="image/png" sizes="64x64" href="/goyave/goyave_64.png"> 11 <link rel="icon" type="image/png" sizes="128x128" href="/goyave/goyave_128.png"> 12 <link rel="icon" type="image/png" sizes="256x256" href="/goyave/goyave_256.png"> 13 <link rel="icon" type="image/png" sizes="512x512" href="/goyave/goyave_512.png"> 14 <meta name="description" content="Goyave is a Golang web API framework aiming at cleanliness, fast development and power."> 15 <meta name="og:title" content="Configuration - Goyave"> 16 <meta name="twitter:title" content="Configuration - Goyave"> 17 <meta name="title" content="Configuration - Goyave"> 18 <meta property="twitter:description" content="Goyave is a Golang web API framework aiming at cleanliness, fast development and power."> 19 <meta property="twitter:image:src" content="https://system-glitch.github.io/goyave/goyave_banner.png"> 20 <meta property="twitter:card" content="summary_large_image"> 21 <meta property="og:type" content="website"> 22 <meta property="og:description" content="Goyave is a Golang web API framework aiming at cleanliness, fast development and power."> 23 <meta property="og:image" content="https://system-glitch.github.io/goyave/goyave_banner.png"> 24 <meta property="og:site_name" content="Goyave"> 25 <link rel="preload" href="/goyave/assets/css/0.styles.589fd562.css" as="style"><link rel="preload" href="/goyave/assets/js/app.092490a7.js" as="script"><link rel="preload" href="/goyave/assets/js/4.75a9cc68.js" as="script"><link rel="preload" href="/goyave/assets/js/1.121dd9ed.js" as="script"><link rel="preload" href="/goyave/assets/js/25.0d463913.js" as="script"><link rel="preload" href="/goyave/assets/js/5.c83f1192.js" as="script"><link rel="prefetch" href="/goyave/assets/js/10.2f07bbf5.js"><link rel="prefetch" href="/goyave/assets/js/11.2d66fdef.js"><link rel="prefetch" href="/goyave/assets/js/12.63171b15.js"><link rel="prefetch" href="/goyave/assets/js/13.770050f3.js"><link rel="prefetch" href="/goyave/assets/js/14.b933d8cf.js"><link rel="prefetch" href="/goyave/assets/js/15.36df2a66.js"><link rel="prefetch" href="/goyave/assets/js/16.ed66719e.js"><link rel="prefetch" href="/goyave/assets/js/17.7bef5f05.js"><link rel="prefetch" href="/goyave/assets/js/18.470b55ed.js"><link rel="prefetch" href="/goyave/assets/js/19.90e0dab8.js"><link rel="prefetch" href="/goyave/assets/js/20.3a300ca3.js"><link rel="prefetch" href="/goyave/assets/js/21.c3fd6053.js"><link rel="prefetch" href="/goyave/assets/js/22.d5569617.js"><link rel="prefetch" href="/goyave/assets/js/23.931b2034.js"><link rel="prefetch" href="/goyave/assets/js/24.1a4755e7.js"><link rel="prefetch" href="/goyave/assets/js/26.3c173a7a.js"><link rel="prefetch" href="/goyave/assets/js/27.9c5b36f2.js"><link rel="prefetch" href="/goyave/assets/js/28.41e055b7.js"><link rel="prefetch" href="/goyave/assets/js/29.b87adf4a.js"><link rel="prefetch" href="/goyave/assets/js/3.ef71e77d.js"><link rel="prefetch" href="/goyave/assets/js/6.2336bf0c.js"><link rel="prefetch" href="/goyave/assets/js/7.d60e55c1.js"><link rel="prefetch" href="/goyave/assets/js/8.2ee33a42.js"><link rel="prefetch" href="/goyave/assets/js/9.8e043d60.js"> 26 <link rel="stylesheet" href="/goyave/assets/css/0.styles.589fd562.css"> 27 </head> 28 <body> 29 <div id="app" data-server-rendered="true"><div class="theme-container"><header class="navbar"><div class="sidebar-button"><svg xmlns="http://www.w3.org/2000/svg" aria-hidden="true" role="img" viewBox="0 0 448 512" class="icon"><path fill="currentColor" d="M436 124H12c-6.627 0-12-5.373-12-12V80c0-6.627 5.373-12 12-12h424c6.627 0 12 5.373 12 12v32c0 6.627-5.373 12-12 12zm0 160H12c-6.627 0-12-5.373-12-12v-32c0-6.627 5.373-12 12-12h424c6.627 0 12 5.373 12 12v32c0 6.627-5.373 12-12 12zm0 160H12c-6.627 0-12-5.373-12-12v-32c0-6.627 5.373-12 12-12h424c6.627 0 12 5.373 12 12v32c0 6.627-5.373 12-12 12z"></path></svg></div> <a href="/goyave/" class="home-link router-link-active"><img src="/goyave/goyave_64.png" alt="Goyave" class="logo"> <span class="site-name can-hide">Goyave</span></a> <div class="links"><div class="user-settings"><a title="Dark theme" href="#" class="settings-button"><svg aria-hidden="true" data-prefix="fas" data-icon="cog" role="img" xmlns="http://www.w3.org/2000/svg" viewBox="0 0 16 16" class="svg-inline--fa fa-cog fa-w-16 settings-icon"><path fill="currentColor" d="M8 0c-4.4 0-8 3.6-8 8s3.6 8 8 8 8-3.6 8-8-3.6-8-8-8zM8 15c-3.9 0-7-3.1-7-7 0-2.4 1.2-4.6 3.2-5.9-0.1 0.6-0.2 1.3-0.2 1.9 0 4.9 4 8.9 8.9 9-1.3 1.3-3 2-4.9 2z"></path></svg></a></div> <div class="search-box"><input aria-label="Search" autocomplete="off" spellcheck="false" value=""> <!----></div> <nav class="nav-links can-hide"><div class="nav-item"><a href="/goyave/guide/" class="nav-link router-link-active"> 30 Guide 31 </a></div><div class="nav-item"><a href="https://pkg.go.dev/github.com/System-Glitch/goyave/v2" target="_blank" rel="noopener noreferrer" class="nav-link external"> 32 pkg.go.dev 33 <svg xmlns="http://www.w3.org/2000/svg" aria-hidden="true" x="0px" y="0px" viewBox="0 0 100 100" width="15" height="15" class="icon outbound"><path fill="currentColor" d="M18.8,85.1h56l0,0c2.2,0,4-1.8,4-4v-32h-8v28h-48v-48h28v-8h-32l0,0c-2.2,0-4,1.8-4,4v56C14.8,83.3,16.6,85.1,18.8,85.1z"></path> <polygon fill="currentColor" points="45.7,48.7 51.3,54.3 77.2,28.5 77.2,37.2 85.2,37.2 85.2,14.9 62.8,14.9 62.8,22.9 71.5,22.9"></polygon></svg></a></div> <a href="https://github.com/System-Glitch/goyave" target="_blank" rel="noopener noreferrer" class="repo-link"> 34 GitHub 35 <svg xmlns="http://www.w3.org/2000/svg" aria-hidden="true" x="0px" y="0px" viewBox="0 0 100 100" width="15" height="15" class="icon outbound"><path fill="currentColor" d="M18.8,85.1h56l0,0c2.2,0,4-1.8,4-4v-32h-8v28h-48v-48h28v-8h-32l0,0c-2.2,0-4,1.8-4,4v56C14.8,83.3,16.6,85.1,18.8,85.1z"></path> <polygon fill="currentColor" points="45.7,48.7 51.3,54.3 77.2,28.5 77.2,37.2 85.2,37.2 85.2,14.9 62.8,14.9 62.8,22.9 71.5,22.9"></polygon></svg></a></nav></div></header> <div class="sidebar-mask"></div> <aside class="sidebar"><nav class="nav-links"><div class="nav-item"><a href="/goyave/guide/" class="nav-link router-link-active"> 36 Guide 37 </a></div><div class="nav-item"><a href="https://pkg.go.dev/github.com/System-Glitch/goyave/v2" target="_blank" rel="noopener noreferrer" class="nav-link external"> 38 pkg.go.dev 39 <svg xmlns="http://www.w3.org/2000/svg" aria-hidden="true" x="0px" y="0px" viewBox="0 0 100 100" width="15" height="15" class="icon outbound"><path fill="currentColor" d="M18.8,85.1h56l0,0c2.2,0,4-1.8,4-4v-32h-8v28h-48v-48h28v-8h-32l0,0c-2.2,0-4,1.8-4,4v56C14.8,83.3,16.6,85.1,18.8,85.1z"></path> <polygon fill="currentColor" points="45.7,48.7 51.3,54.3 77.2,28.5 77.2,37.2 85.2,37.2 85.2,14.9 62.8,14.9 62.8,22.9 71.5,22.9"></polygon></svg></a></div> <a href="https://github.com/System-Glitch/goyave" target="_blank" rel="noopener noreferrer" class="repo-link"> 40 GitHub 41 <svg xmlns="http://www.w3.org/2000/svg" aria-hidden="true" x="0px" y="0px" viewBox="0 0 100 100" width="15" height="15" class="icon outbound"><path fill="currentColor" d="M18.8,85.1h56l0,0c2.2,0,4-1.8,4-4v-32h-8v28h-48v-48h28v-8h-32l0,0c-2.2,0-4,1.8-4,4v56C14.8,83.3,16.6,85.1,18.8,85.1z"></path> <polygon fill="currentColor" points="45.7,48.7 51.3,54.3 77.2,28.5 77.2,37.2 85.2,37.2 85.2,14.9 62.8,14.9 62.8,22.9 71.5,22.9"></polygon></svg></a></nav> <ul class="sidebar-links"><li><section class="sidebar-group collapsable depth-0"><p class="sidebar-heading open"><span>Guide</span> <span class="arrow down"></span></p> <ul class="sidebar-links sidebar-group-items"><li><a href="/goyave/guide/" aria-current="page" class="sidebar-link">Introduction</a></li><li><a href="/goyave/guide/changelog.html" class="sidebar-link">Changelog</a></li><li><a href="/goyave/guide/installation.html" class="sidebar-link">Installation</a></li><li><a href="/goyave/guide/upgrade-guide.html" class="sidebar-link">Upgrade Guide</a></li><li><a href="/goyave/guide/configuration.html" aria-current="page" class="active sidebar-link">Configuration</a><ul class="sidebar-sub-headers"><li class="sidebar-sub-header"><a href="/goyave/guide/configuration.html#introduction" class="sidebar-link">Introduction</a></li><li class="sidebar-sub-header"><a href="/goyave/guide/configuration.html#terminology" class="sidebar-link">Terminology</a></li><li class="sidebar-sub-header"><a href="/goyave/guide/configuration.html#environment-configuration" class="sidebar-link">Environment configuration</a></li><li class="sidebar-sub-header"><a href="/goyave/guide/configuration.html#using-the-configuration" class="sidebar-link">Using the configuration</a></li><li class="sidebar-sub-header"><a href="/goyave/guide/configuration.html#custom-config-entries" class="sidebar-link">Custom config entries</a></li><li class="sidebar-sub-header"><a href="/goyave/guide/configuration.html#configuration-reference" class="sidebar-link">Configuration reference</a></li><li class="sidebar-sub-header"><a href="/goyave/guide/configuration.html#setting-up-https" class="sidebar-link">Setting up HTTPS</a></li></ul></li><li><a href="/goyave/guide/architecture-concepts.html" class="sidebar-link">Architecture Concepts</a></li><li><a href="/goyave/guide/deployment.html" class="sidebar-link">Deployment</a></li><li><a href="/goyave/guide/contribution-guide.html" class="sidebar-link">Contributing to Goyave</a></li></ul></section></li><li><section class="sidebar-group collapsable depth-0"><p class="sidebar-heading"><span>The Basics</span> <span class="arrow right"></span></p> <!----></section></li><li><section class="sidebar-group collapsable depth-0"><p class="sidebar-heading"><span>Advanced</span> <span class="arrow right"></span></p> <!----></section></li></ul> </aside> <main class="page"> <div class="theme-default-content content__default"><h1 id="configuration"><a href="#configuration" class="header-anchor">#</a> Configuration</h1> <p></p><div class="table-of-contents"><ul><li><a href="#introduction">Introduction</a></li><li><a href="#terminology">Terminology</a></li><li><a href="#environment-configuration">Environment configuration</a></li><li><a href="#using-the-configuration">Using the configuration</a><ul><li><a href="#using-environment-variables">Using environment variables</a></li><li><a href="#getting-a-value">Getting a value</a></li><li><a href="#setting-a-value">Setting a value</a></li></ul></li><li><a href="#custom-config-entries">Custom config entries</a></li><li><a href="#configuration-reference">Configuration reference</a><ul><li><a href="#app-category">App category</a></li><li><a href="#server-category">Server category</a></li><li><a href="#database-category">Database category</a></li></ul></li><li><a href="#setting-up-https">Setting up HTTPS</a></li></ul></div><p></p> <h2 id="introduction"><a href="#introduction" class="header-anchor">#</a> Introduction</h2> <p>The Goyave framework lets you configure its core and your application. 42 To configure your application, use the <code>config.json</code> file at your project's root. If you are using the template project, copy <code>config.example.json</code> to <code>config.json</code>. <code>config.json</code> should be ignored in your <code>.gitignore</code> 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 <code>config.example.json</code>.</p> <p>If this config file misses some config entries, the default values will be used. Refer to the <a href="#configuration-reference">configuration reference</a> to know more.</p> <p>All entries are <strong>validated</strong>. 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). That also means that a goroutine trying to change a config entry with the incorrect type will panic.<br> 43 Entries can be registered with a default value, their type and authorized values from any package.</p> <p>Configuration can be used concurrently safely.</p> <p>The following JSON file is an example of default configuration:</p> <div class="language-json extra-class"><pre class="language-json"><code><span class="token punctuation">{</span> 44 <span class="token property">"app"</span><span class="token operator">:</span> <span class="token punctuation">{</span> 45 <span class="token property">"name"</span><span class="token operator">:</span> <span class="token string">"goyave_template"</span><span class="token punctuation">,</span> 46 <span class="token property">"environment"</span><span class="token operator">:</span> <span class="token string">"localhost"</span><span class="token punctuation">,</span> 47 <span class="token property">"debug"</span><span class="token operator">:</span> <span class="token boolean">true</span><span class="token punctuation">,</span> 48 <span class="token property">"defaultLanguage"</span><span class="token operator">:</span> <span class="token string">"en-US"</span> 49 <span class="token punctuation">}</span><span class="token punctuation">,</span> 50 <span class="token property">"server"</span><span class="token operator">:</span> <span class="token punctuation">{</span> 51 <span class="token property">"host"</span><span class="token operator">:</span> <span class="token string">"127.0.0.1"</span><span class="token punctuation">,</span> 52 <span class="token property">"maintenance"</span><span class="token operator">:</span> <span class="token boolean">false</span><span class="token punctuation">,</span> 53 <span class="token property">"protocol"</span><span class="token operator">:</span> <span class="token string">"http"</span><span class="token punctuation">,</span> 54 <span class="token property">"domain"</span><span class="token operator">:</span> <span class="token string">""</span><span class="token punctuation">,</span> 55 <span class="token property">"port"</span><span class="token operator">:</span> <span class="token number">8080</span><span class="token punctuation">,</span> 56 <span class="token property">"httpsPort"</span><span class="token operator">:</span> <span class="token number">8081</span><span class="token punctuation">,</span> 57 <span class="token property">"timeout"</span><span class="token operator">:</span> <span class="token number">10</span><span class="token punctuation">,</span> 58 <span class="token property">"maxUploadSize"</span><span class="token operator">:</span> <span class="token number">10</span><span class="token punctuation">,</span> 59 <span class="token property">"tls"</span><span class="token operator">:</span> <span class="token punctuation">{</span> 60 <span class="token property">"cert"</span><span class="token operator">:</span> <span class="token string">"/path/to/cert"</span><span class="token punctuation">,</span> 61 <span class="token property">"key"</span><span class="token operator">:</span> <span class="token string">"/path/to/key"</span> 62 <span class="token punctuation">}</span><span class="token punctuation">,</span> 63 <span class="token punctuation">}</span><span class="token punctuation">,</span> 64 <span class="token property">"database"</span><span class="token operator">:</span> <span class="token punctuation">{</span> 65 <span class="token property">"connection"</span><span class="token operator">:</span> <span class="token string">"mysql"</span><span class="token punctuation">,</span> 66 <span class="token property">"host"</span><span class="token operator">:</span> <span class="token string">"127.0.0.1"</span><span class="token punctuation">,</span> 67 <span class="token property">"port"</span><span class="token operator">:</span> <span class="token number">3306</span><span class="token punctuation">,</span> 68 <span class="token property">"name"</span><span class="token operator">:</span> <span class="token string">"goyave"</span><span class="token punctuation">,</span> 69 <span class="token property">"username"</span><span class="token operator">:</span> <span class="token string">"root"</span><span class="token punctuation">,</span> 70 <span class="token property">"password"</span><span class="token operator">:</span> <span class="token string">"root"</span><span class="token punctuation">,</span> 71 <span class="token property">"options"</span><span class="token operator">:</span> <span class="token string">"charset=utf8&parseTime=true&loc=Local"</span><span class="token punctuation">,</span> 72 <span class="token property">"maxOpenConnections"</span><span class="token operator">:</span> <span class="token number">20</span><span class="token punctuation">,</span> 73 <span class="token property">"maxIdleConnections"</span><span class="token operator">:</span> <span class="token number">20</span><span class="token punctuation">,</span> 74 <span class="token property">"maxLifetime"</span><span class="token operator">:</span> <span class="token number">300</span><span class="token punctuation">,</span> 75 <span class="token property">"autoMigrate"</span><span class="token operator">:</span> <span class="token boolean">false</span> 76 <span class="token punctuation">}</span> 77 <span class="token punctuation">}</span> 78 </code></pre></div><h2 id="terminology"><a href="#terminology" class="header-anchor">#</a> Terminology</h2> <p><strong>Entry</strong>: a configuration entry is a value accessible using a key.</p> <p><strong>Registering an entry</strong>: informs the framework that an entry with the given key is expected. Registering an entry allows to set a default value to be used if this entry is not provided in an app's configuration file, to enforce a certain type for this entry (for example if it needs to be an integer), and to set a list of allowed values.</p> <p><strong>Category</strong>: a category is represented by a JSON object in your configuration file, delimited by braces. Sub-categories are categories that are not at root level, for example: <code>server.tls</code> is a sub-category of the <code>server</code> category.</p> <h2 id="environment-configuration"><a href="#environment-configuration" class="header-anchor">#</a> Environment configuration</h2> <p>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 <code>GOYAVE_ENV</code>.</p> <p>Since <code>v2.0.0</code>, you can use custom environments.</p> <table><thead><tr><th>GOYAVE_ENV</th> <th>Config file</th></tr></thead> <tbody><tr><td>test</td> <td><code>config.test.json</code></td></tr> <tr><td>production</td> <td><code>config.production.json</code></td></tr> <tr><td><em>custom_env</em></td> <td><code>config.custom_env.json</code></td></tr> <tr><td>local / localhost / <em>not set</em></td> <td><code>config.json</code></td></tr></tbody></table> <h2 id="using-the-configuration"><a href="#using-the-configuration" class="header-anchor">#</a> Using the configuration</h2> <p>Before being able to use the config, import the config package:</p> <div class="language-go extra-class"><pre class="language-go"><code><span class="token keyword">import</span> <span class="token string">"github.com/System-Glitch/goyave/v2/config"</span> 79 </code></pre></div><p>The configuration is loaded automatically when the server starts, but you can reload it manually if needed.</p> <p>When the configuration is loaded, all default values are copied to the newly created map holding the configuration. Then, the configuration file is read, parsed and is applied over. This means that all entries from the file override the default ones. However, if an entry has a default value and the same entry is not present in the configuration file, then it is kept as it is. On the other hand, if an entry is present in the configuration file and not in the default values (meaning that this entry is not expected), a new entry will be registered.This new entry will be subsequently validated using the type of its initial value and have an empty slice as authorized values (meaning it can have any value of its type)</p> <p>The following cases will raise errors when the configuration is being overridden:</p> <ul><li>When the configuration file overrides an entry with a category</li> <li>When the configuration file overrides a category with an entry</li></ul> <h4 id="config-load"><a href="#config-load" class="header-anchor">#</a> config.Load</h4> <table><thead><tr><th>Parameters</th> <th>Return</th></tr></thead> <tbody><tr><td></td> <td><code>error</code></td></tr></tbody></table> <p><strong>Example:</strong></p> <div class="language-go extra-class"><pre class="language-go"><code>config<span class="token punctuation">.</span><span class="token function">Load</span><span class="token punctuation">(</span><span class="token punctuation">)</span> 80 </code></pre></div><h4 id="config-loadfrom"><a href="#config-loadfrom" class="header-anchor">#</a> config.LoadFrom</h4> <p>You may need to load a configuration file from a custom path instead of using the standard one. <code>LoadFrom</code> lets you load a config file from the given path.</p> <table><thead><tr><th>Parameters</th> <th>Return</th></tr></thead> <tbody><tr><td><code>path string</code></td> <td><code>error</code></td></tr></tbody></table> <p><strong>Example:</strong> load the config from the path given through a flag</p> <div class="language-go extra-class"><pre class="language-go"><code><span class="token keyword">import</span> <span class="token punctuation">(</span> 81 <span class="token string">"flag"</span> 82 <span class="token string">"os"</span> 83 84 <span class="token string">"github.com/System-Glitch/goyave/v2"</span> 85 <span class="token string">"github.com/System-Glitch/goyave/v2/config"</span> 86 87 <span class="token comment">//...</span> 88 <span class="token punctuation">)</span> 89 90 <span class="token keyword">func</span> <span class="token function">handleFlags</span><span class="token punctuation">(</span><span class="token punctuation">)</span> <span class="token punctuation">{</span> 91 flag<span class="token punctuation">.</span>Usage <span class="token operator">=</span> <span class="token keyword">func</span><span class="token punctuation">(</span><span class="token punctuation">)</span> <span class="token punctuation">{</span> 92 goyave<span class="token punctuation">.</span>ErrLogger<span class="token punctuation">.</span><span class="token function">Println</span><span class="token punctuation">(</span><span class="token string">"usage: "</span> <span class="token operator">+</span> os<span class="token punctuation">.</span>Args<span class="token punctuation">[</span><span class="token number">0</span><span class="token punctuation">]</span> <span class="token operator">+</span> <span class="token string">" -config=[config]"</span><span class="token punctuation">)</span> 93 flag<span class="token punctuation">.</span><span class="token function">PrintDefaults</span><span class="token punctuation">(</span><span class="token punctuation">)</span> 94 os<span class="token punctuation">.</span><span class="token function">Exit</span><span class="token punctuation">(</span><span class="token number">1</span><span class="token punctuation">)</span> 95 <span class="token punctuation">}</span> 96 97 flag<span class="token punctuation">.</span><span class="token function">String</span><span class="token punctuation">(</span><span class="token string">"config"</span><span class="token punctuation">,</span> <span class="token string">""</span><span class="token punctuation">,</span> <span class="token string">"JSON config file"</span><span class="token punctuation">)</span> 98 flag<span class="token punctuation">.</span><span class="token function">Parse</span><span class="token punctuation">(</span><span class="token punctuation">)</span> 99 100 configDir <span class="token operator">:=</span> flag<span class="token punctuation">.</span><span class="token function">Lookup</span><span class="token punctuation">(</span><span class="token string">"config"</span><span class="token punctuation">)</span> 101 path <span class="token operator">:=</span> configDir<span class="token punctuation">.</span>Value<span class="token punctuation">.</span><span class="token function">String</span><span class="token punctuation">(</span><span class="token punctuation">)</span> 102 <span class="token keyword">if</span> path <span class="token operator">!=</span> configDir<span class="token punctuation">.</span>DefValue <span class="token punctuation">{</span> 103 <span class="token keyword">if</span> err <span class="token operator">:=</span> config<span class="token punctuation">.</span><span class="token function">LoadFrom</span><span class="token punctuation">(</span>path<span class="token punctuation">)</span><span class="token punctuation">;</span> err <span class="token operator">!=</span> <span class="token boolean">nil</span> <span class="token punctuation">{</span> 104 goyave<span class="token punctuation">.</span>ErrLogger<span class="token punctuation">.</span><span class="token function">Println</span><span class="token punctuation">(</span>err<span class="token punctuation">)</span> 105 os<span class="token punctuation">.</span><span class="token function">Exit</span><span class="token punctuation">(</span>goyave<span class="token punctuation">.</span>ExitInvalidConfig<span class="token punctuation">)</span> 106 <span class="token punctuation">}</span> 107 <span class="token punctuation">}</span> 108 <span class="token punctuation">}</span> 109 110 <span class="token keyword">func</span> <span class="token function">main</span><span class="token punctuation">(</span><span class="token punctuation">)</span> <span class="token punctuation">{</span> 111 <span class="token function">handleFlags</span><span class="token punctuation">(</span><span class="token punctuation">)</span> 112 113 <span class="token keyword">if</span> err <span class="token operator">:=</span> goyave<span class="token punctuation">.</span><span class="token function">Start</span><span class="token punctuation">(</span>route<span class="token punctuation">.</span>Register<span class="token punctuation">)</span><span class="token punctuation">;</span> err <span class="token operator">!=</span> <span class="token boolean">nil</span> <span class="token punctuation">{</span> 114 os<span class="token punctuation">.</span><span class="token function">Exit</span><span class="token punctuation">(</span>err<span class="token punctuation">.</span><span class="token punctuation">(</span><span class="token operator">*</span>goyave<span class="token punctuation">.</span>Error<span class="token punctuation">)</span><span class="token punctuation">.</span>ExitCode<span class="token punctuation">)</span> 115 <span class="token punctuation">}</span> 116 <span class="token punctuation">}</span> 117 </code></pre></div><h3 id="using-environment-variables"><a href="#using-environment-variables" class="header-anchor">#</a> Using environment variables</h3> <p><span class="badge tip" style="vertical-align:top;" data-v-15b7b770>Since v3.0.0</span></p> <p>You can use environment variables in your configuration file. Environment variables are identified by the following syntax: <code>${VARIABLE_NAME}</code>.</p> <div class="language-json extra-class"><pre class="language-json"><code><span class="token punctuation">{</span> 118 <span class="token property">"database"</span><span class="token operator">:</span> <span class="token punctuation">{</span> 119 <span class="token property">"host"</span><span class="token operator">:</span> <span class="token string">"${DB_HOST}"</span> 120 <span class="token punctuation">}</span> 121 <span class="token punctuation">}</span> 122 </code></pre></div><p><strong>Note:</strong> <em>This syntax is strict. If the string doesn't start with <code>${</code> or doesn't end with <code>}</code>, it will not be considered an environment variable.</em></p> <p><code>int</code>, <code>float64</code> and <code>bool</code> values are supported. If the configuration entry is expected to be of one of these types, the content of the environment variable will be automatically converted. If the conversion fails, a configuration loading error will be returned.</p> <h3 id="getting-a-value"><a href="#getting-a-value" class="header-anchor">#</a> Getting a value</h3> <p>All entries are accessible using <strong>dot-separated paths</strong>. If you want to access the <code>name</code> entry in the <code>app</code> category, the key will be <code>app.name</code>.</p> <h4 id="config-get"><a href="#config-get" class="header-anchor">#</a> config.Get</h4> <p>Get a generic config entry.</p> <p>Prefer using the <code>GetString</code>, <code>GetBool</code>, <code>GetInt</code> and <code>GetFloat</code> accessors. If you need a type not covered by those accessors, use <code>config.Get</code>. You may need to type-assert the returned value before using it. You can do so safely as the config values and types are validated.</p> <p>Panics if the entry doesn't exist.</p> <table><thead><tr><th>Parameters</th> <th>Return</th></tr></thead> <tbody><tr><td><code>key string</code></td> <td><code>interface{}</code> or panic</td></tr></tbody></table> <p><strong>Example:</strong></p> <div class="language-go extra-class"><pre class="language-go"><code>config<span class="token punctuation">.</span><span class="token function">Get</span><span class="token punctuation">(</span><span class="token string">"app.name"</span><span class="token punctuation">)</span> <span class="token comment">// "goyave"</span> 123 </code></pre></div><h4 id="config-getstring"><a href="#config-getstring" class="header-anchor">#</a> config.GetString</h4> <p>Get a string config entry. Panics if the entry doesn't exist or is not a <code>string</code> or if it doesn't exist.</p> <table><thead><tr><th>Parameters</th> <th>Return</th></tr></thead> <tbody><tr><td><code>key string</code></td> <td><code>string</code> or panic</td></tr></tbody></table> <p><strong>Example:</strong></p> <div class="language-go extra-class"><pre class="language-go"><code>config<span class="token punctuation">.</span><span class="token function">GetString</span><span class="token punctuation">(</span><span class="token string">"server.protocol"</span><span class="token punctuation">)</span> <span class="token comment">// "http"</span> 124 </code></pre></div><h4 id="config-getbool"><a href="#config-getbool" class="header-anchor">#</a> config.GetBool</h4> <p>Get a bool config entry. Panics if the entry doesn't exist or is not a <code>bool</code> or if it doesn't exist.</p> <table><thead><tr><th>Parameters</th> <th>Return</th></tr></thead> <tbody><tr><td><code>key string</code></td> <td><code>bool</code> or panic</td></tr></tbody></table> <p><strong>Example:</strong></p> <div class="language-go extra-class"><pre class="language-go"><code>config<span class="token punctuation">.</span><span class="token function">GetBool</span><span class="token punctuation">(</span><span class="token string">"app.debug"</span><span class="token punctuation">)</span> <span class="token comment">// true</span> 125 </code></pre></div><h4 id="config-getint"><a href="#config-getint" class="header-anchor">#</a> config.GetInt</h4> <p><span class="badge tip" style="vertical-align:top;" data-v-15b7b770>Since v3.0.0</span></p> <p>Get an int config entry. Panics if the entry doesn't exist or is not an <code>int</code> or if it doesn't exist.</p> <table><thead><tr><th>Parameters</th> <th>Return</th></tr></thead> <tbody><tr><td><code>key string</code></td> <td><code>int</code> or panic</td></tr></tbody></table> <p><strong>Example:</strong></p> <div class="language-go extra-class"><pre class="language-go"><code>config<span class="token punctuation">.</span><span class="token function">GetInt</span><span class="token punctuation">(</span><span class="token string">"server.port"</span><span class="token punctuation">)</span> <span class="token comment">// 8080</span> 126 </code></pre></div><h4 id="config-getfloat"><a href="#config-getfloat" class="header-anchor">#</a> config.GetFloat</h4> <p><span class="badge tip" style="vertical-align:top;" data-v-15b7b770>Since v3.0.0</span></p> <p>Get a float config entry. Panics if the entry doesn't exist or is not a <code>float64</code> or if it doesn't exist.</p> <table><thead><tr><th>Parameters</th> <th>Return</th></tr></thead> <tbody><tr><td><code>key string</code></td> <td><code>float64</code> or panic</td></tr></tbody></table> <p><strong>Example:</strong></p> <div class="language-go extra-class"><pre class="language-go"><code>config<span class="token punctuation">.</span><span class="token function">GetInt</span><span class="token punctuation">(</span><span class="token string">"server.port"</span><span class="token punctuation">)</span> <span class="token comment">// 8080</span> 127 </code></pre></div><h4 id="config-has"><a href="#config-has" class="header-anchor">#</a> config.Has</h4> <p>Check if a config entry exists.</p> <table><thead><tr><th>Parameters</th> <th>Return</th></tr></thead> <tbody><tr><td><code>key string</code></td> <td><code>bool</code></td></tr></tbody></table> <p><strong>Example:</strong></p> <div class="language-go extra-class"><pre class="language-go"><code>config<span class="token punctuation">.</span><span class="token function">Has</span><span class="token punctuation">(</span><span class="token string">"app.name"</span><span class="token punctuation">)</span> <span class="token comment">// true</span> 128 </code></pre></div><h3 id="setting-a-value"><a href="#setting-a-value" class="header-anchor">#</a> Setting a value</h3> <p>You can set a config value at runtime with the <code>config.Set(key, value)</code> function. Bear in mind that this change <strong>temporary</strong> 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: your application will panic and revert changes if the validation doesn't pass.</p> <p>Use <code>nil</code> to unset a value.</p> <ul><li>A category cannot be replaced with an entry.</li> <li>An entry cannot be replaced with a category.</li> <li>New categories can be created with they don't already exist.</li> <li>New entries can be created if they don't already exist. This new entry will be subsequently validated using the type of its initial value and have an empty slice as authorized values (meaning it can have any value of its type)</li></ul> <h4 id="config-set"><a href="#config-set" class="header-anchor">#</a> config.Set</h4> <table><thead><tr><th>Parameters</th> <th>Return</th></tr></thead> <tbody><tr><td><code>key string</code></td> <td><code>void</code> or panic</td></tr> <tr><td><code>value interface{}</code></td> <td></td></tr></tbody></table> <p><strong>Example:</strong></p> <div class="language-go extra-class"><pre class="language-go"><code>config<span class="token punctuation">.</span><span class="token function">Set</span><span class="token punctuation">(</span><span class="token string">"app.name"</span><span class="token punctuation">,</span> <span class="token string">"my awesome app"</span><span class="token punctuation">)</span> 129 </code></pre></div><h2 id="custom-config-entries"><a href="#custom-config-entries" class="header-anchor">#</a> Custom config entries</h2> <p>Configuration can be expanded. It is very likely that a plugin or a package you're developing is using some form of options. These options can be added to the configuration system so it is not needed to set them in the code or to make some wiring.</p> <h4 id="config-register"><a href="#config-register" class="header-anchor">#</a> config.Register</h4> <p>Register a new config entry and its validation.</p> <p>Each module should register its config entries in an <code>init()</code> function, even if they don't have a default value, in order to ensure they will be validated.</p> <p>Each module should use its own category and use a name both expressive and unique to avoid collisions. For example, the <code>auth</code> package registers, among others, <code>auth.basic.username</code> and <code>auth.jwt.expiry</code>, thus creating a category for its package, and two subcategories for its features.</p> <p>To register an entry without a default value (only specify how it will be validated), set <code>Entry.Value</code> to <code>nil</code>.</p> <p>Panics if an entry already exists for this key and is not identical to the one passed as parameter of this function. On the other hand, if the entries are identical, no conflict is expected so the configuration is left in its current state.</p> <table><thead><tr><th>Parameters</th> <th>Return</th></tr></thead> <tbody><tr><td><code>key string</code></td> <td><code>void</code> or panic</td></tr> <tr><td><code>kind config.Entry</code></td> <td></td></tr></tbody></table> <p><strong>Example:</strong></p> <div class="language-go extra-class"><pre class="language-go"><code><span class="token keyword">func</span> <span class="token function">init</span><span class="token punctuation">(</span><span class="token punctuation">)</span> <span class="token punctuation">{</span> 130 config<span class="token punctuation">.</span><span class="token function">Register</span><span class="token punctuation">(</span><span class="token string">"my-plugin.name"</span><span class="token punctuation">,</span> config<span class="token punctuation">.</span>Entry<span class="token punctuation">{</span> 131 Value<span class="token punctuation">:</span> <span class="token string">"default value"</span><span class="token punctuation">,</span> 132 Type<span class="token punctuation">:</span> reflect<span class="token punctuation">.</span>String<span class="token punctuation">,</span> 133 AuthorizedValues<span class="token punctuation">:</span> <span class="token punctuation">[</span><span class="token punctuation">]</span><span class="token keyword">interface</span><span class="token punctuation">{</span><span class="token punctuation">}</span><span class="token punctuation">{</span><span class="token punctuation">}</span><span class="token punctuation">,</span> 134 <span class="token punctuation">}</span><span class="token punctuation">)</span> 135 136 <span class="token comment">// Without a default value (only validation)</span> 137 config<span class="token punctuation">.</span><span class="token function">Register</span><span class="token punctuation">(</span><span class="token string">"my-plugin.protocol"</span><span class="token punctuation">,</span> config<span class="token punctuation">.</span>Entry<span class="token punctuation">{</span> 138 Value<span class="token punctuation">:</span> <span class="token boolean">nil</span><span class="token punctuation">,</span> 139 Type<span class="token punctuation">:</span> reflect<span class="token punctuation">.</span>String<span class="token punctuation">,</span> 140 AuthorizedValues<span class="token punctuation">:</span> <span class="token punctuation">[</span><span class="token punctuation">]</span><span class="token keyword">interface</span><span class="token punctuation">{</span><span class="token punctuation">}</span><span class="token punctuation">{</span><span class="token string">"ftp"</span><span class="token punctuation">,</span> <span class="token string">"sftp"</span><span class="token punctuation">,</span> <span class="token string">"scp"</span><span class="token punctuation">}</span><span class="token punctuation">,</span> 141 <span class="token punctuation">}</span><span class="token punctuation">)</span> 142 <span class="token punctuation">}</span> 143 </code></pre></div><h2 id="configuration-reference"><a href="#configuration-reference" class="header-anchor">#</a> Configuration reference</h2> <h3 id="app-category"><a href="#app-category" class="header-anchor">#</a> App category</h3> <table><thead><tr><th>Entry</th> <th>Type</th> <th>Accepted values</th> <th>Default</th> <th>Note</th></tr></thead> <tbody><tr><td>name</td> <td><code>string</code></td> <td>any</td> <td>"goyave"</td> <td></td></tr> <tr><td>environment</td> <td><code>string</code></td> <td>any</td> <td>"localhost"</td> <td></td></tr> <tr><td>debug</td> <td><code>bool</code></td> <td><code>true</code>, <code>false</code></td> <td><code>true</code></td> <td>When activated, print stacktrace on error and sends error message in response. <strong>Disable this in production!</strong></td></tr> <tr><td>defaultLanguage</td> <td><code>string</code></td> <td>any</td> <td>"en-US"</td> <td>See the <a href="/goyave/guide/advanced/localization.html">Localization</a></td></tr></tbody></table> <h3 id="server-category"><a href="#server-category" class="header-anchor">#</a> Server category</h3> <table><thead><tr><th>Entry</th> <th>Type</th> <th>Accepted values</th> <th>Default</th> <th>Note</th></tr></thead> <tbody><tr><td>host</td> <td><code>string</code></td> <td>any</td> <td>"127.0.0.1"</td> <td></td></tr> <tr><td>domain</td> <td><code>string</code></td> <td>any</td> <td>""</td> <td>Used for URL generation Leave empty to use IP instead.</td></tr> <tr><td>protocol</td> <td><code>string</code></td> <td>"http", "https"</td> <td>"http"</td> <td>See the <a href="#setting-up-https">HTTPS</a> section</td></tr> <tr><td>port</td> <td><code>int</code></td> <td>any</td> <td><code>8080</code></td> <td></td></tr> <tr><td>httpsPort</td> <td><code>int</code></td> <td>any</td> <td><code>8081</code></td> <td></td></tr> <tr><td>timeout</td> <td><code>int</code></td> <td>any</td> <td><code>10</code></td> <td>Timeout in seconds</td></tr> <tr><td>maxUploadSize</td> <td><code>float64</code></td> <td>any</td> <td><code>10</code></td> <td>Maximum size of the request, in MiB</td></tr> <tr><td>maintenance</td> <td><code>bool</code></td> <td><code>true</code>, <code>false</code></td> <td><code>false</code></td> <td>If <code>true</code>, start the server in maintenance mode. (Always return HTTP 503)</td></tr></tbody></table> <h4 id="tls-sub-category"><a href="#tls-sub-category" class="header-anchor">#</a> TLS sub-category</h4> <table><thead><tr><th>Entry</th> <th>Type</th> <th>Accepted values</th> <th>Default</th> <th>Note</th></tr></thead> <tbody><tr><td>cert</td> <td><code>string</code></td> <td>any</td> <td>none</td> <td>Path to your TLS cert</td></tr> <tr><td>key</td> <td><code>string</code></td> <td>any</td> <td>none</td> <td>Path to your TLS key</td></tr></tbody></table> <h3 id="database-category"><a href="#database-category" class="header-anchor">#</a> Database category</h3> <table><thead><tr><th>Entry</th> <th>Type</th> <th>Accepted values</th> <th>Default</th> <th>Note</th></tr></thead> <tbody><tr><td>connection</td> <td><code>string</code></td> <td>"none", "mysql", "postgres", "sqlite3", "mssql"</td> <td>"none"</td> <td>See the <a href="/goyave/guide/basics/database.html">Database</a> guide</td></tr> <tr><td>host</td> <td><code>string</code></td> <td>any</td> <td>"127.0.0.1"</td> <td></td></tr> <tr><td>port</td> <td><code>int</code></td> <td>any</td> <td><code>3306</code></td> <td></td></tr> <tr><td>name</td> <td><code>string</code></td> <td>any</td> <td>"goyave"</td> <td></td></tr> <tr><td>username</td> <td><code>string</code></td> <td>any</td> <td>"root"</td> <td></td></tr> <tr><td>password</td> <td><code>string</code></td> <td>any</td> <td>"root"</td> <td></td></tr> <tr><td>otions</td> <td><code>string</code></td> <td>any</td> <td>"charset=utf8&parseTime=true&loc=Local"</td> <td></td></tr> <tr><td>maxOpenConnections</td> <td><code>int</code></td> <td>any</td> <td><code>20</code></td> <td></td></tr> <tr><td>maxIdleConnections</td> <td><code>int</code></td> <td>any</td> <td><code>20</code></td> <td></td></tr> <tr><td>maxLifetime</td> <td><code>int</code></td> <td>any</td> <td><code>300</code></td> <td>The maximum time (in seconds) a connection may be reused.</td></tr> <tr><td>autoMigrate</td> <td><code>bool</code></td> <td><code>true</code>, <code>false</code></td> <td><code>false</code></td> <td>When activated, migrate all registered models at startup</td></tr></tbody></table> <h2 id="setting-up-https"><a href="#setting-up-https" class="header-anchor">#</a> Setting up HTTPS</h2> <p>Setting up HTTPS on your Goyave application is easy. First, turn <code>server.protocol</code> to <code>https</code> in the config. Then, add the <code>server.tls.cert</code> and <code>server.tls.key</code> entries in the config. These two entries represent respectively the path to your TLS certificate and your TLS key.</p> <p><strong>Certbot example:</strong></p> <div class="language-json extra-class"><pre class="language-json"><code><span class="token punctuation">{</span> 144 ... 145 <span class="token property">"server"</span><span class="token operator">:</span> <span class="token punctuation">{</span> 146 <span class="token property">"protocol"</span><span class="token operator">:</span> <span class="token string">"https"</span><span class="token punctuation">,</span> 147 <span class="token property">"tls"</span><span class="token operator">:</span> <span class="token punctuation">{</span> 148 <span class="token property">"cert"</span><span class="token operator">:</span> <span class="token string">"/etc/letsencrypt/live/mydomain.com/cert.pem"</span><span class="token punctuation">,</span> 149 <span class="token property">"key"</span><span class="token operator">:</span> <span class="token string">"/etc/letsencrypt/live/mydomain.com/privkey.pem"</span> 150 <span class="token punctuation">}</span> 151 <span class="token punctuation">}</span><span class="token punctuation">,</span> 152 ... 153 <span class="token punctuation">}</span> 154 </code></pre></div><p>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.</p></div> <footer class="page-edit"><div class="edit-link"><a href="https://github.com/System-Glitch/goyave/edit/master/docs_src/src/guide/configuration.md" target="_blank" rel="noopener noreferrer">Edit this page on GitHub</a> <svg xmlns="http://www.w3.org/2000/svg" aria-hidden="true" x="0px" y="0px" viewBox="0 0 100 100" width="15" height="15" class="icon outbound"><path fill="currentColor" d="M18.8,85.1h56l0,0c2.2,0,4-1.8,4-4v-32h-8v28h-48v-48h28v-8h-32l0,0c-2.2,0-4,1.8-4,4v56C14.8,83.3,16.6,85.1,18.8,85.1z"></path> <polygon fill="currentColor" points="45.7,48.7 51.3,54.3 77.2,28.5 77.2,37.2 85.2,37.2 85.2,14.9 62.8,14.9 62.8,22.9 71.5,22.9"></polygon></svg></div> <!----></footer> <div class="page-nav"><p class="inner"><span class="prev"> 155 ← 156 <a href="/goyave/guide/upgrade-guide.html" class="prev"> 157 Upgrade Guide 158 </a></span> <span class="next"><a href="/goyave/guide/architecture-concepts.html"> 159 Architecture Concepts 160 </a> 161 → 162 </span></p></div> </main></div><div class="global-ui"><!----></div></div> 163 <script src="/goyave/assets/js/app.092490a7.js" defer></script><script src="/goyave/assets/js/4.75a9cc68.js" defer></script><script src="/goyave/assets/js/1.121dd9ed.js" defer></script><script src="/goyave/assets/js/25.0d463913.js" defer></script><script src="/goyave/assets/js/5.c83f1192.js" defer></script> 164 </body> 165 </html>