Skip to content

Commit 0638c88

Browse files
linawolfsarahmccarthy123
linawolf
and
sarahmccarthy123
authored
[TASK] Write information on application context (#520)
* [TASK] Write information on application context Releases: main, 13.4, 12.4 * Apply suggestions from code review Co-authored-by: Sarah McCarthy <[email protected]> * Update Documentation/Installation/ApplicationContext.rst Co-authored-by: Sarah McCarthy <[email protected]> --------- Co-authored-by: Sarah McCarthy <[email protected]>
1 parent d8da9fe commit 0638c88

File tree

8 files changed

+207
-36
lines changed

8 files changed

+207
-36
lines changed

‎Documentation/Installation/ApplicationContext.rst‎

Lines changed: 138 additions & 0 deletions
Original file line numberDiff line numberDiff line change
@@ -0,0 +1,138 @@
1+
:navigation-title: Application context
2+
.. include:: /Includes.rst.txt
3+
4+
.. index:: Environment; Configuration; .env ; dotenv
5+
6+
.. _environment-phpconfig:
7+
.. _environment-configuration:
8+
.. _application-context:
9+
10+
====================================================
11+
TYPO3 Application context: Development or Production
12+
====================================================
13+
14+
.. figure:: _ApplicationContext/ApplicationContextInformation.png
15+
:alt: Screenshot showing the current application context in the "System Information" box
16+
17+
The current application context is displayed on the top-right in the "System Information" box
18+
19+
A TYPO3 instance is often used in different contexts that can adapt to your
20+
needs.
21+
22+
You can use the application context to differentiate between different
23+
environments / servers.
24+
25+
There are 3 major application context groups:
26+
27+
`Development`
28+
To be used during development. Debugging is enabled by default.
29+
`Production`
30+
Debugging and deprecation logs are deactivated by default.
31+
`Testing`
32+
To be used in automated testing.
33+
34+
You can define arbitrary strings as a subcontext for example `Development/Local`
35+
or `Production/Stage`.
36+
37+
.. todo: Link to application context in TYPO3 explained, once that chapter is written
38+
39+
.. contents::
40+
41+
.. _set-ApplicationContext:
42+
43+
Setting the application context
44+
===============================
45+
46+
If the application context is not set it is `Production` by default so that you
47+
don't have to do anything on the production server.
48+
49+
.. todo: Link to application context in TYPO3 explained, once that chapter is written
50+
51+
In DDEV you should set the application context to `Development/Local` to enable
52+
debugging and different site configurations for DDEV and your live server.
53+
54+
Create a file called :file:`docker-compose.context.yaml` in your :path:`.ddev`
55+
path with the following content:
56+
57+
.. literalinclude:: _ApplicationContext/_docker-compose.context.yaml
58+
:caption: [project root]/.ddev/docker-compose.context.yaml
59+
60+
Restart DDEV using
61+
62+
.. code-block:: bash
63+
64+
ddev restart
65+
66+
.. _development-settings:
67+
68+
Local development
69+
=================
70+
71+
When you :ref:`installed TYPO3 with DDEV <install>`, DDEV automatically created
72+
a file called :path:`config/system/additional.php` for you. This file includes
73+
server settings needed only during development, including:
74+
75+
* A connection to the local database in DDEV
76+
* Configuration of Mailpit to enable debugging of emails
77+
* Image magic configuration so that images can be scaled and edited
78+
* Enabling enhanced error reporting
79+
80+
You should not :ref:`deploy <deployment>` this file to your production server
81+
but create one just for the production server.
82+
See section :ref:`production-settings`
83+
84+
.. _production-settings:
85+
86+
Production environment
87+
======================
88+
89+
It is not recommended to put credentials into a file that is kept under version
90+
control. However, many other settings should be kept under version control.
91+
92+
We recommend putting all configuration containing credentials into a special
93+
file that is not kept under version control and include it in your
94+
:path:`config/system/additional.php`.
95+
96+
Create a file called :file:`config/system/credentials.php`:
97+
98+
.. literalinclude:: _ApplicationContext/_credentials.php
99+
:caption: config/system/credentials.php
100+
101+
.. important::
102+
Add :file:`config/system/credentials.php` to your `.gitignore` so that it
103+
is never put under version control.
104+
105+
You can now include this file in your
106+
:path:`config/system/additional.php`:
107+
108+
.. literalinclude:: _ApplicationContext/_additional.php
109+
:caption: config/system/additional.php
110+
111+
The following steps are needed for a secure production context:
112+
113+
* :ref:`Generate a unique encryption key <t3coreapi:security-encryption-key-generate>`
114+
and put it in `$customChanges['SYS']['encryptionKey']` in your
115+
:file:`config/system/credentials.php`.
116+
* Choose a new install tool password and put its hash into
117+
`$customChanges['BE']['installToolPassword']`.
118+
* Replace the database credentials in the
119+
`$customChanges['DB']['Connections']['Default']` section with
120+
database credentials for your server.
121+
122+
Further settings important for security can be made directly in the
123+
:path:`config/system/additional.php`:
124+
125+
.. literalinclude:: _ApplicationContext/_additional-2.php
126+
:caption: config/system/additional.php
127+
128+
Please refer to the security guide in getting started to check which settings
129+
are currently recommended for a secure production environment:
130+
131+
:ref:`Global TYPO3 configuration options <t3coreapi:security-global-typo3-options>`
132+
133+
Suggested configurations might change in future security bulletins.
134+
135+
.. todo: link to chapter about security / security bulletins once it is written.
136+
137+
You can put any of the suggested changes into the `$customChanges` array of
138+
your :path:`config/system/additional.php`.

‎Documentation/Installation/EnvironmentConfiguration.rst‎

Lines changed: 0 additions & 35 deletions
This file was deleted.

‎Documentation/Installation/Index.rst‎

Lines changed: 6 additions & 1 deletion
Original file line numberDiff line numberDiff line change
@@ -15,7 +15,7 @@ Installation
1515
SystemRequirements/Index
1616
Install
1717
DeployTYPO3
18-
EnvironmentConfiguration
18+
ApplicationContext
1919

2020
.. card-grid::
2121
:columns: 1
@@ -40,6 +40,11 @@ Installation
4040
After you have installed TYPO3 locally, learn how to move your result
4141
to a web server.
4242

43+
.. card:: :ref:`Application context <application-context>`
44+
45+
Use the TYPO3 application context to manage settings for
46+
development and production.
47+
4348
.. _installation_advanced:
4449

4550
Advanced installation topics

‎Documentation/Installation/_ApplicationContext/ApplicationContextInformation.png‎

39 KB
Loading

‎Documentation/Installation/_ApplicationContext/_additional-2.php‎

Lines changed: 24 additions & 0 deletions
Original file line numberDiff line numberDiff line change
@@ -0,0 +1,24 @@
1+
<?php
2+
3+
defined('TYPO3') or die();
4+
5+
$customChanges = [
6+
'BE' => [
7+
'debug' => '0',
8+
],
9+
'FE' => [
10+
'debug' => '0',
11+
],
12+
'SYS' => [
13+
'trustedHostsPattern' => 'SERVER_NAME', // keep this if it is working on your server
14+
'devIPmask' => '127.0.0.1,::1', // localhost oly
15+
'displayErrors' => 0, // Turn off error reporting
16+
],
17+
];
18+
19+
$GLOBALS['TYPO3_CONF_VARS'] = array_replace_recursive($GLOBALS['TYPO3_CONF_VARS'], (array)$customChanges);
20+
$file = realpath(__DIR__) . '/credentials.php';
21+
if (is_file($file)) {
22+
include_once($file);
23+
$GLOBALS['TYPO3_CONF_VARS'] = array_replace_recursive($GLOBALS['TYPO3_CONF_VARS'], (array)$customChanges);
24+
}

‎Documentation/Installation/_ApplicationContext/_additional.php‎

Lines changed: 13 additions & 0 deletions
Original file line numberDiff line numberDiff line change
@@ -0,0 +1,13 @@
1+
<?php
2+
3+
defined('TYPO3') or die();
4+
5+
$customChanges = [
6+
];
7+
8+
$GLOBALS['TYPO3_CONF_VARS'] = array_replace_recursive($GLOBALS['TYPO3_CONF_VARS'], (array)$customChanges);
9+
$file = realpath(__DIR__) . '/credentials.php';
10+
if (is_file($file)) {
11+
include_once($file);
12+
$GLOBALS['TYPO3_CONF_VARS'] = array_replace_recursive($GLOBALS['TYPO3_CONF_VARS'], (array)$customChanges);
13+
}

‎Documentation/Installation/_ApplicationContext/_credentials.php‎

Lines changed: 21 additions & 0 deletions
Original file line numberDiff line numberDiff line change
@@ -0,0 +1,21 @@
1+
<?php
2+
3+
defined('TYPO3') or die();
4+
$customChanges = [
5+
'BE' => [
6+
'installToolPassword' => 'some encrypted string',
7+
],
8+
'DB' => [
9+
'Connections' => [
10+
'Default' => [
11+
'dbname' => 'my_db',
12+
'host' => 'localhost',
13+
'password' => '<secure password>',
14+
'user' => 'my_db_user',
15+
],
16+
],
17+
],
18+
'SYS' => [
19+
'encryptionKey' => 'replace with generated encryption key',
20+
],
21+
];

‎Documentation/Installation/_ApplicationContext/_docker-compose.context.yaml‎

Lines changed: 5 additions & 0 deletions
Original file line numberDiff line numberDiff line change
@@ -0,0 +1,5 @@
1+
version: '3.6'
2+
services:
3+
web:
4+
environment:
5+
- TYPO3_CONTEXT=Development/Local

0 commit comments

Comments
 (0)