From 16dc632ef94d8c6daee6691d8064c831fb5c7a0b Mon Sep 17 00:00:00 2001 From: gevorgmansuryan Date: Mon, 2 Sep 2024 03:59:22 +0400 Subject: [PATCH 1/7] Update Docs to new Debug mode handling and .env support --- docs/admin/installation.md | 18 ++++++++---------- docs/admin/security.md | 18 ++++-------------- docs/develop/environment.md | 25 +++++++++++++++---------- 3 files changed, 27 insertions(+), 34 deletions(-) diff --git a/docs/admin/installation.md b/docs/admin/installation.md index 90e1bbc..c938bcb 100644 --- a/docs/admin/installation.md +++ b/docs/admin/installation.md @@ -192,20 +192,18 @@ The [virtual server](server-setup.md#nginx) configuration for NGINX is already p ## Enable production mode -By default HumHub is shipped in debug mode. This means that error messages are shown with maximum details directly to the users. In addition, the performance is reduced because no caching or compressed assets are used. +By default, HumHub is shipped in debug mode. After successful installation it's automatically switches to production mode. -To activate Production Mode, edit the index.php file and comment out the following lines. -To comment out lines, the line must begin with: // +You can see the current mode at `Administration -> Information`. -Example (/var/www/humhub/index.php): +## Enable debug mode -```php -// comment out the following two lines when deployed to production -// defined('YII_DEBUG') or define('YII_DEBUG', true); -// defined('YII_ENV') or define('YII_ENV', 'dev'); -``` +To activate Debug Mode: +1. create new file called `.env` in project root +2. copy contents of `.env.example` to `.env` +3. make sure that value of `HUMHUB_DEBUG` is `1` -You can see the current mode at ``Administration -> Information``. +You can see the current mode at `Administration -> Information`. ## Verify diff --git a/docs/admin/security.md b/docs/admin/security.md index b404f33..f3c6f30 100644 --- a/docs/admin/security.md +++ b/docs/admin/security.md @@ -8,21 +8,11 @@ This guide describes recommended configurations and practices in order to keep y Enable Production Mode -------------------------- -By default HumHub is operating in _DEBUG_ mode, which besides others uses a different error handling and non combined -assets. Before opening your installation to the public you should enable the production mode first by commenting out the -following lines of the `index.php` file within your HumHub root directory: +1. By default, HumHub is shipped in debug mode. After successful installation it's automatically switches to production mode. +If you enabled `DEBUG` mode earlier via `.env`, before opening your installation to the public make sure that `DEBUG=0`. +> If you do not have file `.env` in project root just skip this -```php -[...] -// comment out the following two lines when deployed to production -// defined('YII_DEBUG') or define('YII_DEBUG', true); -// defined('YII_ENV') or define('YII_ENV', 'dev'); -[...] -``` - -> Note: In this example the lines are already commented out. - -You should also delete the `index-test.php` file in your HumHub root directory if existing. +2. You should also delete the `index-test.php` file in your HumHub root directory if existing. Protected Directories --------------------- diff --git a/docs/develop/environment.md b/docs/develop/environment.md index 02a5ee3..7172d60 100644 --- a/docs/develop/environment.md +++ b/docs/develop/environment.md @@ -51,7 +51,8 @@ Please refer to the [Installation Guide](../admin/installation.md) for further i ### Quick Notes -- Make sure the `debug` mode is enabled (default), see [Enable Production Mode](../admin/security.md#enable-production-mode) +- Copy contents of `.env.example` to `.env` +- Make sure the `debug` mode is enabled (default), see [Enable Debug Mode](../admin/installation.md#enable-debug-mode) - Disable caching under `Administration -> Settings -> Advanced -> Caching -> None` - Use file based mailing `Administration -> Settings -> Advanced -> E-Mail` @@ -65,15 +66,11 @@ have to run `queue/run` command manually in order to execute queued tasks as not ### Module Loader Path The default path under which HumHub searches for installed modules is `@humhub/protected/modules`. Additional search paths -can be configured within `@humhub/protected/config/common.php` as follows: +can be configured within with `.env` as follows: -```php -// @humhub/protected/config/common.php -return [ - 'params' => [ - 'moduleAutoloadPaths' => ['/some/folder/modules'], - ], -] +```env +// @humhub/.env +HUMHUB_CONFIG.PARAMS.MODULE_AUTOLOAD_PATHS=['/some/folder/modules', '/some/other-folder/modules'] ``` This separation should be done for custom modules which are not in [the marketplace](https://marketplace.humhub.com/) (e.g, `@app/custom-modules`) or for your development environment in order to define a central module directory @@ -82,8 +79,16 @@ for different test installations and prevent interference with marketplace modul ### Yii Debug Module You may want to enable the [Yii Debug Module](http://www.yiiframework.com/doc-2.0/ext-debug-index.html) for detailed -request and query debugging. Just add the following block to your local web configuration `protected/config/web.php`: +request and query debugging. Just add the following block to your local web configuration: + +in `.env` +```env +// @humhub/.env +HUMHUB_CONFIG.BOOSTRAP=['debug'] +HUMHUB_CONFIG.MODULES.DEBUG='{"class":"yii\\\debug\\\Module", "allowedIPs": ["127.0.0.1", "::1"]}' +``` +or in `protected/config/web.php` ```php return [ 'bootstrap' => ['debug'], From 5d12e23a534d494e04951526a182755252d26dd4 Mon Sep 17 00:00:00 2001 From: gevorgmansuryan Date: Mon, 2 Sep 2024 04:01:02 +0400 Subject: [PATCH 2/7] Update Docs to new Debug mode handling and .env support --- docs/develop/environment.md | 2 +- 1 file changed, 1 insertion(+), 1 deletion(-) diff --git a/docs/develop/environment.md b/docs/develop/environment.md index 7172d60..d9f07da 100644 --- a/docs/develop/environment.md +++ b/docs/develop/environment.md @@ -52,7 +52,7 @@ Please refer to the [Installation Guide](../admin/installation.md) for further i ### Quick Notes - Copy contents of `.env.example` to `.env` -- Make sure the `debug` mode is enabled (default), see [Enable Debug Mode](../admin/installation.md#enable-debug-mode) +- Make sure the `DEBUG` mode is enabled (default), see [Enable Debug Mode](../admin/installation.md#enable-debug-mode) - Disable caching under `Administration -> Settings -> Advanced -> Caching -> None` - Use file based mailing `Administration -> Settings -> Advanced -> E-Mail` From c6b055231bbb593a50880ef13080b9b433d3da1a Mon Sep 17 00:00:00 2001 From: mbumpalumpa <92554196+mbumpalumpa@users.noreply.github.com> Date: Tue, 3 Sep 2024 10:14:59 +0200 Subject: [PATCH 3/7] Small FIxes @luke- I'm a bit confused about the usage of backticks, as we use both single and double backticks in different places. I changed the ones I saw to double backticks, as most of the previous commits (from 4 years ago) use double backticks. --- docs/admin/installation.md | 24 ++++++++++++------------ docs/admin/security.md | 20 ++++++++++---------- docs/develop/environment.md | 14 ++++++-------- 3 files changed, 28 insertions(+), 30 deletions(-) diff --git a/docs/admin/installation.md b/docs/admin/installation.md index c938bcb..e29b957 100644 --- a/docs/admin/installation.md +++ b/docs/admin/installation.md @@ -92,7 +92,7 @@ The following configuration settings can be made directly in HumHub via the brow HumHub sends emails to the users e.g. during the registration, password recovery, notifications or for daily summaries. -A valid transport and a sender e-mail address must be provided for this purpose. This can be configured in the web interface under ``Administration -> Settings -> Advanced -> E-Mail`. +A valid transport and a sender e-mail address must be provided for this purpose. This can be configured in the web interface under ``Administration > Settings > Advanced > E-Mail`. :::note You should use a `noreply` sender e-mail address sice reply by mail is currently not supported. @@ -106,7 +106,7 @@ You can use external SMTP services like SendGrid, Postmark, Amazon SES, Mailgun By default HumHub uses the time zone of the web server. However, the time zone of the database server (MariaDB) is the relevant one. If these time zones differs or the server was moved to another location, you need to change this time zone. -You can switch the time zone at: ``Administration -> Settings -> General -> Server timezone`` +You can switch the time zone at: ``Administration > Settings > General > Server timezone`` If you are not sure which time zone is configured on your Maria DB server, you can query the time zone with the following SQL statement. @@ -192,28 +192,28 @@ The [virtual server](server-setup.md#nginx) configuration for NGINX is already p ## Enable production mode -By default, HumHub is shipped in debug mode. After successful installation it's automatically switches to production mode. +By default, HumHub is shipped in debug mode. After a successful installation, it automatically switches to production mode. -You can see the current mode at `Administration -> Information`. +You can see the current mode at ``Administration > Information``. ## Enable debug mode -To activate Debug Mode: -1. create new file called `.env` in project root -2. copy contents of `.env.example` to `.env` -3. make sure that value of `HUMHUB_DEBUG` is `1` +Activating Debug Mode: +1. Create a new file called ``.env`` in the project root. +2. Copy the contents of ``.env.example`` into the newly created ``.env`` file. +3. Ensure that the value of ``HUMHUB_DEBUG`` is set to ``1``. -You can see the current mode at `Administration -> Information`. +You can see the current mode at ``Administration > Information``. ## Verify - **Cronjobs** - You can find the last execution and number of open background jobs at: ``Administration -> Information -> Background jobs`` + You can find the last execution and number of open background jobs at: ``Administration > Information > Background jobs`` - **Error log** - Check the log for error messages and warnings. These can be viewed directly in Humhub under YXZ. ``Administration -> Information -> Logging`` + Check the log for error messages and warnings. These can be viewed directly in Humhub under YXZ. ``Administration > Information > Logging`` - **Protected folders** @@ -227,7 +227,7 @@ You can see the current mode at `Administration -> Information`. - **Production Mode** - Make sure that no warning about the ``Debug mode`` appears under ``Administration -> Information -> About HumHub``. + Make sure that no warning about the ``Debug mode`` appears under ``Administration > Information > About HumHub``. ## Staging/Test Environment diff --git a/docs/admin/security.md b/docs/admin/security.md index f3c6f30..a1d556e 100644 --- a/docs/admin/security.md +++ b/docs/admin/security.md @@ -8,11 +8,11 @@ This guide describes recommended configurations and practices in order to keep y Enable Production Mode -------------------------- -1. By default, HumHub is shipped in debug mode. After successful installation it's automatically switches to production mode. -If you enabled `DEBUG` mode earlier via `.env`, before opening your installation to the public make sure that `DEBUG=0`. -> If you do not have file `.env` in project root just skip this +1. By default, HumHub is shipped in debug mode. After a successful installation, it automatically switches to production mode. +If you previously enabled ``DEBUG`` mode via the ``.env`` file, make sure that ``HUMHUB_DEBUG=0`` before opening your installation to the public. +> If you do not have a ``.env`` file in the project root, you can skip this step. -2. You should also delete the `index-test.php` file in your HumHub root directory if existing. +2. Delete the ``index-test.php`` file in your HumHub root directory if it exists. Protected Directories --------------------- @@ -24,9 +24,9 @@ Limit User Access If you're running a private social network, make sure the user registration has been disabled or the approval system for new users has been enabled. -- Disable user registration: `Administration -> Users -> Settings -> Anonymous users can register` -- Enable user approvals: `Administration -> Users -> Settings -> Require group admin approval after registration` -- Make sure guest access is disabled: `Administration -> Users -> Settings -> Allow limited access for non-authenticated users (guests)` +- Disable user registration: `Administration > Users > Settings > Anonymous users can register` +- Enable user approvals: `Administration > Users > Settings > Require group admin approval after registration` +- Make sure guest access is disabled: `Administration > Users > Settings > Allow limited access for non-authenticated users (guests)` Password Strength Configuration ------------------------------- @@ -170,7 +170,7 @@ Please refer to the following links for more information about the CSP and the c `csp-report-only`: -This section can be used to define a csp rule, which will only log violations to `Administration -> Information -> Logging` +This section can be used to define a csp rule, which will only log violations to `Administration > Information > Logging` rather than blocking the resources on the client. This can be used to test csp rules on your installation. **CSP Reporting:** @@ -197,7 +197,7 @@ properly with your security configuration, please contact the module owner or re This section assembles some guidelines and restrictions regarding custom CSP settings in HumHub. -- The HumHub core currently requires `img-src data:` for page icon and image upload `Administration -> Settings -> Appearance` +- The HumHub core currently requires `img-src data:` for page icon and image upload `Administration > Settings > Appearance` - When using the enterprise edition you should allow `https://www.humhub.org` for `frame-src` - When noticing any issues with external modules, please inform the module owner. - When developing custom modules, try to test against the strictest csp rules (see default acceptance test csp rules) and provide @@ -210,6 +210,6 @@ As an admin you'll receive notifications about new HumHub releases. We strongly stable version if possible. Check the [update guide](updating.md) for more information about updating your HumHub installation. -Furthermore, you should regularly check the `Administration -> Modules -> Available Updates` section for module updates. +Furthermore, you should regularly check the `Administration > Modules > Available Updates` section for module updates. We take security very seriously, and we're continuously improving the security features of HumHub. diff --git a/docs/develop/environment.md b/docs/develop/environment.md index d9f07da..17afde1 100644 --- a/docs/develop/environment.md +++ b/docs/develop/environment.md @@ -51,10 +51,10 @@ Please refer to the [Installation Guide](../admin/installation.md) for further i ### Quick Notes -- Copy contents of `.env.example` to `.env` -- Make sure the `DEBUG` mode is enabled (default), see [Enable Debug Mode](../admin/installation.md#enable-debug-mode) -- Disable caching under `Administration -> Settings -> Advanced -> Caching -> None` -- Use file based mailing `Administration -> Settings -> Advanced -> E-Mail` +- Copy the contents of ``.env.example`` into the newly created ``.env`` file. +- Make sure the ``DEBUG`` mode is enabled (default), see [Enable Debug Mode](../admin/installation.md#enable-debug-mode) +- Disable caching under ``Administration > Settings > Advanced > Caching > None`` +- Use file based mailing ``Administration > Settings > Advanced > E-Mail`` ### Queue configuration @@ -65,8 +65,7 @@ have to run `queue/run` command manually in order to execute queued tasks as not ### Module Loader Path -The default path under which HumHub searches for installed modules is `@humhub/protected/modules`. Additional search paths -can be configured within with `.env` as follows: +The default path where HumHub searches for installed modules is ``@humhub/protected/modules``. Additional search paths can be configured in the ``.env`` file as follows: ```env // @humhub/.env @@ -78,8 +77,7 @@ for different test installations and prevent interference with marketplace modul ### Yii Debug Module -You may want to enable the [Yii Debug Module](http://www.yiiframework.com/doc-2.0/ext-debug-index.html) for detailed -request and query debugging. Just add the following block to your local web configuration: +You may want to enable the [Yii Debug Module](http://www.yiiframework.com/doc-2.0/ext-debug-index.html) for detailed request and query debugging. Just add the following block to your local web configuration:: in `.env` ```env From eb6b45cf77f65aeed661854384d6f04fc7adae2d Mon Sep 17 00:00:00 2001 From: mbumpalumpa <92554196+mbumpalumpa@users.noreply.github.com> Date: Wed, 4 Sep 2024 20:50:53 +0200 Subject: [PATCH 4/7] Update troubleshooting.md @luke- something like this? Idk if this is the right place within the Troubleshooting docs, but since the Community is mentioned here, it might be an appropriate spot. Anyway, let me know if this is ok. --- docs/admin/troubleshooting.md | 3 +++ 1 file changed, 3 insertions(+) diff --git a/docs/admin/troubleshooting.md b/docs/admin/troubleshooting.md index 9bb8af0..c96b99c 100644 --- a/docs/admin/troubleshooting.md +++ b/docs/admin/troubleshooting.md @@ -80,6 +80,9 @@ Support Community There is also an active support community at: http://community.humhub.com +Debug Mode +----------------- +For instructions on how to enable debug mode, refer to the [Enable Debug Mode](../admin/installation.md#enable-debug-mode) guide. Github - Bugtracker ------------------- From f0b98807423b6c4b7b97b33c917d5654cf14f977 Mon Sep 17 00:00:00 2001 From: mbumpalumpa <92554196+mbumpalumpa@users.noreply.github.com> Date: Thu, 5 Sep 2024 10:03:26 +0200 Subject: [PATCH 5/7] Docs Fix @luke- hopefully, this is what you meant. I added logging as part of the "Debug Mode", but did you want it as a separate section instead? --- docs/admin/installation.md | 8 -------- docs/admin/troubleshooting.md | 8 +++++++- 2 files changed, 7 insertions(+), 9 deletions(-) diff --git a/docs/admin/installation.md b/docs/admin/installation.md index e29b957..2d5c523 100644 --- a/docs/admin/installation.md +++ b/docs/admin/installation.md @@ -196,14 +196,6 @@ By default, HumHub is shipped in debug mode. After a successful installation, it You can see the current mode at ``Administration > Information``. -## Enable debug mode - -Activating Debug Mode: -1. Create a new file called ``.env`` in the project root. -2. Copy the contents of ``.env.example`` into the newly created ``.env`` file. -3. Ensure that the value of ``HUMHUB_DEBUG`` is set to ``1``. - -You can see the current mode at ``Administration > Information``. ## Verify diff --git a/docs/admin/troubleshooting.md b/docs/admin/troubleshooting.md index c96b99c..89e2ade 100644 --- a/docs/admin/troubleshooting.md +++ b/docs/admin/troubleshooting.md @@ -82,7 +82,13 @@ There is also an active support community at: http://community.humhub.com Debug Mode ----------------- -For instructions on how to enable debug mode, refer to the [Enable Debug Mode](../admin/installation.md#enable-debug-mode) guide. + +Enabling Debug Mode: +1. Create a new file called ``.env`` in the project root. +2. Copy the contents of ``.env.example`` into the newly created ``.env`` file. +3. Ensure that the value of ``HUMHUB_DEBUG`` is set to ``1``. + +To see which mode HumHub is currently operating in, navigate to ``Administration > Information``. To access log entries, go to ``Administration > Information > Logging`` Github - Bugtracker ------------------- From ca7fe8077511bb15a84e4706c6d4354436fe4377 Mon Sep 17 00:00:00 2001 From: Lucas Bartholemy Date: Sun, 20 Oct 2024 19:51:43 +0200 Subject: [PATCH 6/7] Update environment.md --- docs/develop/environment.md | 6 +++--- 1 file changed, 3 insertions(+), 3 deletions(-) diff --git a/docs/develop/environment.md b/docs/develop/environment.md index 17afde1..c71d956 100644 --- a/docs/develop/environment.md +++ b/docs/develop/environment.md @@ -69,7 +69,7 @@ The default path where HumHub searches for installed modules is ``@humhub/protec ```env // @humhub/.env -HUMHUB_CONFIG.PARAMS.MODULE_AUTOLOAD_PATHS=['/some/folder/modules', '/some/other-folder/modules'] +HUMHUB_CONFIG__PARAMS__MODULE_AUTOLOAD_PATHS=['/some/folder/modules', '/some/other-folder/modules'] ``` This separation should be done for custom modules which are not in [the marketplace](https://marketplace.humhub.com/) (e.g, `@app/custom-modules`) or for your development environment in order to define a central module directory @@ -82,8 +82,8 @@ You may want to enable the [Yii Debug Module](http://www.yiiframework.com/doc-2. in `.env` ```env // @humhub/.env -HUMHUB_CONFIG.BOOSTRAP=['debug'] -HUMHUB_CONFIG.MODULES.DEBUG='{"class":"yii\\\debug\\\Module", "allowedIPs": ["127.0.0.1", "::1"]}' +HUMHUB_CONFIG__BOOSTRAP=['debug'] +HUMHUB_CONFIG__MODULES__DEBUG='{"class":"yii\\\debug\\\Module", "allowedIPs": ["127.0.0.1", "::1"]}' ``` or in `protected/config/web.php` From bcdb8e7f2c4ab708eca351ee92371678bfd7afee Mon Sep 17 00:00:00 2001 From: Lucas Bartholemy Date: Sun, 20 Oct 2024 19:52:35 +0200 Subject: [PATCH 7/7] Update installation.md --- docs/admin/installation.md | 17 ----------------- 1 file changed, 17 deletions(-) diff --git a/docs/admin/installation.md b/docs/admin/installation.md index 2d5c523..ae8091a 100644 --- a/docs/admin/installation.md +++ b/docs/admin/installation.md @@ -102,23 +102,6 @@ If you installed a local SMTP server e.g. [Postfix](server-setup.md#postfix), yo You can use external SMTP services like SendGrid, Postmark, Amazon SES, Mailgun or any other SMTP server with the ``SMTP`` as ``Mail Transport Type`` option. -### Time Zone - -By default HumHub uses the time zone of the web server. However, the time zone of the database server (MariaDB) is the relevant one. If these time zones differs or the server was moved to another location, you need to change this time zone. - -You can switch the time zone at: ``Administration > Settings > General > Server timezone`` - -If you are not sure which time zone is configured on your Maria DB server, you can query the time zone with the following SQL statement. - -```sql -mysql> SELECT @@global.time_zone, @@session.time_zone; -``` - - -:::note -Each registered user can also set its own primary time zone in the profile settings. -::: - ## Pretty URLs By default, the HumHub URL includes a index.php file part and looks like https://example.com/index.php?r=dashboard%2Fdashboard.