Configuration

Lychee’s core configuration is managed using a .env file. It probably exists already in your directory, but if not it can be created by copying .env.example. The options which are already included in the .env file should be sufficient to cover the necessary configuration for the vast majority of all use-cases and setups. Using other options than those included in the .env file should rarely be necessary. However, this page contains a more complete list of the available options, incl. some highly advanced ones, together with descriptions and default values. For non-core options (for example UI options), take a look at Settings.

APP_ENV only has special meaning to Lychee and its dependencies when it is exactly production:

• production (default) — the safe default for any public-facing install. Generic error pages are shown instead of stack traces, APP_DEBUG_LATENCY is always ignored, and the Content Security Policy is enforced.
• Anything else (e.g. local, development) — treated as non-production. This is what unlocks the Development options below, and is required by the Log Viewer if you want to use it outside of an admin session (per the official .env.example: “it is not possible to enable Log Viewer in production; if you wish to enable it, also switch your APP_ENV to local”).

Never set APP_ENV to anything other than production on a public-facing install — combined with APP_DEBUG, non-production values relax several security defaults.

These options enable or disable entire features of Lychee. Most of them are advanced and rarely need to be touched.

Lychee supports MySQL/MariaDB, SQLite and PostgreSQL as database backends. Microsoft SQL Server can be used, but is unsupported. The configuration is managed using the DB_ variables.

Some hosting providers give you a single URL containing all the information needed to configure your database. Therefore, Lychee has a DATABASE_URL option which only needs the database connection type. For example:

DB_CONNECTION=mysql
DATABASE_URL="mysql://root:password@127.0.0.1/forge?charset=UTF-8"

If this applies to your hosting provider, you can skip the other DB configuration steps.

The configuration is exactly the same for both systems.

Supported mailers are smtp, ses, mailgun, postmark or sendmail, which you can set using MAIL_DRIVER.

SES can be configured using AWS settings. See AWS configuration.

Lychee can use various services as cache driver to store temporary data. The driver is set using CACHE_DRIVER and supports: apc, array, file, memcached, redis or dynamodb.

Base options are configured using AWS options. You need to create a table, please refer to the Laravel docs.

Also see Redis.

There are no config options, however, you need to run php artisan cache:table to use this option.

Lychee can interact with various third-party services. You can find config options for them here.

To use Redis, you need the PhpRedis PHP extension.

Lychee can authenticate users against an LDAP or Active Directory server, alongside or instead of local accounts.

Lychee can delegate login to a number of external OAuth/OpenID providers. Each provider needs its own client ID and secret, obtained from the provider. Unless stated otherwise, *_REDIRECT_URI should be left at its default value.

These options configure the connection to the external AI Vision microservices used for facial recognition and NSFW classification. They are kept out of the database-backed settings so the service URL and shared API key are never exposed through the admin settings UI.

Payment options gate the webshop checkout (requires Pro). See Payments for the full setup guide for each provider.

Support for token based authentication used by API requests.

Sessions are stored in the same locations as cache. You change the used driver using SESSION_DRIVER.

These options add extra allowed sources to Lychee’s default Content Security Policy. Each accepts a comma-separated list of origins.

Of these, only APP_DEBUG_LATENCY is hard-gated by APP_ENV in code (it is a no-op while APP_ENV is production). The others aren’t technically blocked in production, but doing so is unsupported and may affect stability, performance, or expose debugging information.

You can look at the files in the config/ folder. They contain some options you can’t configure using environmental variables and you are able to adapt Lychee completely to your needs.

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 cache driver locally than you do on your production server.

To make this a cinch, Lychee utilizes the DotEnv PHP library by Vance Lucas. In a fresh Lychee installation, the root directory of your application will contain a .env.example file. You should make a copy of this file as .env.

Your .env file should not be committed to your application’s 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.

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. You may also create a .env.testing file. This file will override the .env file when running PHPUnit tests or executing Artisan commands with the --env=testing option.

All variables in your .env files are parsed as strings, so some reserved values have been created to allow you to return a wider range of types from the env() function:

If you need to define an environment variable with a value that contains spaces, you may do so by enclosing the value in double quotes.

APP_NAME="My Application"

All of the variables listed in this file will be loaded into the $_ENV PHP super-global when your application receives a request. However, you may use the env helper to retrieve values from these variables in your configuration files. In fact, if you review the Lychee configuration files, you will notice several of the options already using this helper:

'debug' => env('APP_DEBUG', false),

The second value passed to the env function is the “default value”. This value will be used if no environment variable exists for the given key.

The current application environment is determined via the APP_ENV variable from your .env file. You may access this value via the environment method on the App facade:

$environment = App::environment();

You may also pass arguments to the environment method to check if the environment matches a given value. The method will return true if the environment matches any of the given values:

if (App::environment('development')) {
    // The environment is development
}

if (App::environment(['development', 'production'])) {
    // The environment is either development OR production...
}

When an exception is uncaught and the APP_DEBUG environment variable is true, the debug page will show all environment variables and their contents. In some cases you may want to obscure certain variables. You may do this by updating the debug_blacklist option in your config/app.php configuration file.

Some variables are available in both the environment variables and the server / request data. Therefore, you may need to blacklist them for both $_ENV and $_SERVER:

return [

    // ...

    'debug_blacklist' => [
        '_ENV' => [
            'APP_KEY',
            'DB_PASSWORD',
        ],

        '_SERVER' => [
            'APP_KEY',
            'DB_PASSWORD',
        ],

        '_POST' => [
            'password',
        ],
    ],
];

You may easily access your configuration values using the global config helper function 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:

$value = config('app.timezone');

To set configuration values at runtime, pass an array to the config helper:

config(['app.timezone' => 'America/Chicago']);

To give your application a speed boost, you should cache all of your configuration files into a single file using the config:cache Artisan command. This will combine all of the configuration options for your application into a single file which will be loaded quickly by the framework.

You should typically run the php artisan config:cache command as part of your production deployment routine. The command should not be run during local development as configuration options will frequently need to be changed during the course of your application’s development.

When your application is in maintenance mode, a custom view will be displayed for all requests into your application. This makes it easy to “disable” your application while it is updating or when you are performing maintenance. A maintenance mode check is included in the default middleware stack for your application. If the application is in maintenance mode, a MaintenanceModeException will be thrown with a status code of 503.

To enable maintenance mode, execute the down Artisan command:

php artisan down

You may also provide message and retry options to the down command. The message value may be used to display or log a custom message, while the retry value will be set as the Retry-After HTTP header’s value:

php artisan down --message="Upgrading Database" --retry=60

Even while in maintenance mode, specific IP addresses or networks may be allowed to access the application using the command’s allow option:

php artisan down --allow=127.0.0.1 --allow=192.168.0.0/16

To disable maintenance mode, use the up command:

php artisan up