Skip to main content
version 1.0.0

Configuration

Introduction

All the configuration files for the Athenna framework are stored in the config directory. Each option is documented, so feel free to look through the files and get familiar with the options available to you.

These configuration files allow you to configure things like your database connection information, your filesystem information to handle file uploads, as well as various other core configuration values.

Environment configuration

It is often helpful to have different configuration values based on the environment where the application is running. For example, you may wish to use a different storage driver locally than you do on your production server.

To make this a cinch, Athenna utilizes the dotenv Node.js library. In a fresh Athenna installation, the root directory of your application will contain a .env.example file that defines many common environment variables. During the Athenna installation process, this file will automatically be copied to .env.

Athenna default .env file contains some common configuration values that may differ based on whether your application is running locally or on a production. These values are then retrieved from various Athenna configuration files within the config directory using Athenna Env function.

If you are developing with a team, you may wish to continue including a .env.example file with your application. By putting placeholder values in the example configuration file, other developers on your team can clearly see which environment variables are needed to run your application.

tip

Any variable in your .env file can be overridden by external environment variables such as server-level or system-level environment variables. But off course you can turn off this behavior setting the OVERRIDE_ENV=true variable before running your application, if this variable is set to true, all environment variables set in .env will override the externals.

danger

Your .env file should not be committed to your application source control, since each developer/server using your application could require a different environment configuration. Furthermore, this would be a security risk in the event an intruder gains access to your source control repository, since any sensitive credentials would get exposed.

Determining the current environment

Before loading your application's environment variables, Athenna determines if either the NODE_ENV environment variable has been externally provided or if the --env Artisan argument has been specified. If so, Athenna will attempt to load an .env.${NODE_ENV} file if it exists. If it does not exist, the default .env file will be loaded.

Running providing --env argument for artisan:

node artisan serve --env=local

Running providing NODE_ENV externally:

NODE_ENV=local node artisan serve

If NODE_ENV is not set, and you have not provided the --env Artisan argument, Athenna will first load the .env file to get the NODE_ENV that is inside it, than Athenna will attempt to load an .env.${NODE_ENV} file if it exists. Check the example:

This is the default .env file that comes in Athenna project:

HOST=localhost
PORT=(1335)
NODE_ENV=local

APP_NAME=Athenna
APP_DEBUG=(true)
APP_URL=http://${HOST}:${PORT}
APP_DOMAIN=${HOST}
APP_DOCUMENTATION=${APP_URL}
APP_SOURCE=https://github.com/AthennaIO

LOG_HTTP=(true)
LOG_CHANNEL=application

If you create a new .env.local file in your project root path, Athenna will load it and replace all the values of .env:

HOST=localhost
PORT=(3030)
NODE_ENV=local

APP_NAME=Athenna Local
APP_DEBUG=(true)
APP_URL=http://localhost:3030
APP_DOMAIN=${HOST}
APP_DOCUMENTATION=${APP_URL}
APP_SOURCE=https://github.com/MyGithubUserHere/MyRepositoryHere

LOG_HTTP=(true)
LOG_CHANNEL=application

Get an environment variable value

You can get environment variables using the Env() function. If APP_NAME cannot be found, the constant appName will have the value Athenna:

const defaultValue = 'Athenna'

const appName = Env('APP_NAME', defaultValue)

All variables in your .env files are always parsed as strings. But the Env function has an auto cast system to parse it for you when you call the function to get the value:

.envEnv()
true"true"
(true)true
"(false)"false
10"10"
(10)10
"(10)"10
{"name":"Paulo"}"{"name":"Paulo"}"
({"name":"Paulo"}){ name: 'Paulo' }
"({"name":"Paulo"})"{ name: 'Paulo' }
tip

Maybe you want to force that your environment variable have the parentheses chars (your-value) or (true). For that, the Env function has the third parameter called autoCast that by default is always true, if you set as false it will not cast the value for you.

process.env.APP_DEBUG = '(true)'

const defaultValue = false
const autoCast = false

console.log(Env('APP_DEBUG', defaultValue)) // true
console.log(Env('APP_DEBUG', defaultValue, autoCast)) // '(true)'

Environment variables can parse other environment variables too. See the example above:

HOST=localhost
PORT=1335

APP_DOMAIN=http://${HOST}:${PORT}
/** @type {string} */
console.log(Env('APP_DOMAIN')) // "http://localhost:1335"

Get a configuration value

You may easily access your configuration values using the global Config helper class from anywhere in your application. The configuration values may be accessed using "dot (.)" syntax, which includes the name of the file and option you wish to access. A default value may also be specified and will be returned if the configuration option does not exist:

/** @type {string} */
const name = Config.get('app.name', 'Athenna')

console.log(name) // MyAppName

Debug mode

The debug option in your config/app.js configuration file determines how much information about your application is actually displayed to you and for who is going to consume your application. By default, this option is set to respect the value of the APP_DEBUG environment variable, which is stored in your .env file.

For local development, you should set the APP_DEBUG environment variable to true. In your production and pipelines environment, this value should always be false. If the variable is set to true in production, you risk exposing sensitive configuration values to your application's end users.