Add .env file configuration to documentation

[marc-farre]

I think we should mention the new .env file in:

• https://docs.humhub.org/docs/admin/advanced-configuration
• https://docs.humhub.org/docs/admin/updating#upgrade-manually -> Restore individual files

[luke-]

@Semir1212 @mbumpalumpa Can you take care of it?

[Semir1212]

@marc-farre I am having difficulties understanding the topic. Could you please write a few lines for the documentation so that we don't get it wrong?

[marc-farre]

@Semir1212 it's about the new .env file: https://github.com/humhub/humhub/blob/develop/.env.example
The idea is to update the doc about the configuration file, because since 1.17:

• part of the configuration settings are done in this new file instead of protected/config/common.php
• upgrading HH manually requires keeping this file alongside with the .htaccess.

But I'm seeing that there is already a similar issue: https://github.com/humhub/humhub-internal/issues/437

And an open PR where most of the work is already done: https://github.com/humhub/documentation/pull/143/files

However, the 2 mentioned pages are not included in this PR:
https://docs.humhub.org/docs/admin/advanced-configuration
https://docs.humhub.org/docs/admin/updating#upgrade-manually -> Restore individual files

[Semir1212]

@marc-farre Thank you, could you please look into the PR and add the missing parts?

[luke-]

@gevorgmansuryan Can you please help here?

[gevorgmansuryan]

HumHub's .env Documentation

The HumHub's .env file provides a mechanism for mapping environment variables to the configuration array used by the Yii framework. This allows for clean separation of configuration and code.

---

Overview

The HumHub's .env file mechanism is not enabled by default. It is designed for advanced users who want to customize their HumHub configuration in a flexible way. To enable it, users can create a .env file by copying the provided .env.example template:

cp .env.example .env

Afterward, users can populate the .env file with their custom configurations.

Important: Be sure that the contents of the .env file are not accessible to the web. Make sure to secure it using proper file permissions or server configuration to prevent unauthorized access.

---

Key Features

• Environment-Specific Prefixes:

  • HUMHUB_FIXED_SETTINGS: Immutable settings.
  • HUMHUB_CONFIG: General Yii configuration.
  • HUMHUB_WEB_CONFIG: Web application-specific configuration.
  • HUMHUB_CLI_CONFIG: Console application-specific configuration.
  • HUMHUB_ALIASES: Yii alias definitions.

• Array Depth Separator:
  Uses __ to represent nested keys in arrays.

• Key Conversion:
  Converts environment variable segments into camelCase.

• Automatic Value Normalization:
  Supports JSON decoding and boolean value conversion.

• Alias Support:
  Maps environment-defined aliases to Yii aliases.

---

Debug Mode

The HUMHUB_DEBUG environment variable controls Yii's debugging and environment settings.

Behavior

• When HUMHUB_DEBUG=true:
  • Sets YII_DEBUG to true.
  • Sets YII_ENV to dev.
• When HUMHUB_DEBUG=false or not set:
  • Sets YII_DEBUG to false.
  • Sets YII_ENV to prod.

Example

HUMHUB_DEBUG=true

Resulting Constants:

define('YII_DEBUG', true);
define('YII_ENV', 'dev');

HUMHUB_DEBUG=false

Resulting Constants:

defined('YII_DEBUG') or define('YII_DEBUG', false);
defined('YII_ENV') or define('YII_ENV', 'prod');

---

Supported Prefixes

HUMHUB_FIXED_SETTINGS

• Purpose: Defines fixed settings under params['fixed-settings'].
• Example:

  HUMHUB_FIXED_SETTINGS__APP__NAME=MyApp
  HUMHUB_FIXED_SETTINGS__APP__VERSION=1.0.0

  Resulting Configuration:

  $config['params']['fixed-settings']['app']['name'] = 'MyApp';
  $config['params']['fixed-settings']['app']['version'] = '1.0.0';

---

HUMHUB_CONFIG

• Purpose: General Yii configuration.
• Example:

  HUMHUB_CONFIG__COMPONENTS__URL_MANAGER__ENABLE_PRETTY_URL=true
  HUMHUB_CONFIG__COMPONENTS__URL_MANAGER__SHOW_SCRIPT_NAME=false

  Resulting Configuration:

  $config['components']['urlManager']['enablePrettyUrl'] = true;
  $config['components']['urlManager']['showScriptName'] = false;

---

HUMHUB_WEB_CONFIG

• Purpose: Web application-specific configuration.
• Example:

  HUMHUB_WEB_CONFIG__COMPONENTS__ASSET_MANAGER__FORCE_COPY=true

  Resulting Configuration:

  $config['components']['assetManager']['forceCopy'] = true;

---

HUMHUB_CLI_CONFIG

• Purpose: Console application-specific configuration.
• Example:

  HUMHUB_CLI_CONFIG__COMPONENTS__CACHE__CLASS=FileCache

  Resulting Configuration:

  $config['components']['cache']['class'] = 'FileCache';

---

HUMHUB_ALIASES

• Purpose: Maps aliases for Yii.
• Example:

  HUMHUB_ALIASES__WEBROOT=/var/www/app
  HUMHUB_ALIASES__UPLOADS=/var/www/app/uploads

  Resulting Aliases:

  Yii::setAlias('@webroot', '/var/www/app');
  Yii::setAlias('@uploads', '/var/www/app/uploads');

---

Value Normalization

• Boolean Values:
  Strings like true and false are converted to booleans.

  HUMHUB_CONFIG__COMPONENTS__URL_MANAGER__ENABLE_PRETTY_URL=true

  $config['components']['urlManager']['enablePrettyUrl'] = true;

• JSON Decoding:
  Strings are decoded into arrays or objects.

  HUMHUB_CONFIG__PARAMS__SUPPORTED_LANGUAGES=["en", "de", "fr"]

  $config['params']['supportedLanguages'] = ['en', 'de', 'fr'];

Example Configuration

Sample .env File

HUMHUB_FIXED_SETTINGS__APP__NAME=MyApp
HUMHUB_CONFIG__COMPONENTS__URL_MANAGER__ENABLE_PRETTY_URL=true
HUMHUB_WEB_CONFIG__COMPONENTS__ASSET_MANAGER__FORCE_COPY=true
HUMHUB_CLI_CONFIG__COMPONENTS__CACHE__CLASS=FileCache
HUMHUB_ALIASES__WEBROOT=/var/www/app

Resulting Configuration

$config = [
    'params' => [
        'fixed-settings' => [
            'app' => [
                'name' => 'MyApp',
            ],
        ],
    ],
    'components' => [
        'urlManager' => [
            'enablePrettyUrl' => true,
        ],
        'assetManager' => [
            'forceCopy' => true,
        ],
        'cache' => [
            'class' => 'FileCache',
        ],
    ],
    'aliases' => [
        '@webroot' => '/var/www/app',
    ],
];

[gevorgmansuryan]

@luke- @Semir1212 pls check