You signed in with another tab or window. Reload to refresh your session.You signed out in another tab or window. Reload to refresh your session.You switched accounts on another tab or window. Reload to refresh your session.Dismiss alert
Copy file name to clipboardExpand all lines: configuration/blackfire.md
+20-1Lines changed: 20 additions & 1 deletion
Display the source diff
Display the rich diff
Original file line number
Diff line number
Diff line change
@@ -19,4 +19,23 @@ Note: You can obtain the IDs and Tokens used in the above from within your Black
19
19
20
20
To use the Blackfire CLI Tool, you can run `warden blackfire [arguments]`.
21
21
22
-
For more information on the CLI tool, please see [Profiling CLI Commands](https://blackfire.io/docs/cookbooks/profiling-cli) in Blackfire's documentation.
22
+
For more information on the CLI tool, please see [Profiling CLI Commands](https://blackfire.io/docs/cookbooks/profiling-cli) in Blackfire's documentation.
23
+
24
+
## Browser Profiling
25
+
26
+
Blackfire provides browser extensions that let you profile any page directly from the toolbar. Install the extension for your browser, log in to your Blackfire account, navigate to the page you want to profile, and click the **Profile** button in the extension.
27
+
28
+
For a full walkthrough, see [Profiling HTTP Requests with a Browser](https://docs.blackfire.io/profiling-cookbooks/profiling-http-via-browser) in Blackfire's documentation.
29
+
30
+
### Browser extensions
31
+
32
+
*[Firefox extension](https://docs.blackfire.io/integrations/browsers/firefox) — **recommended**, supports all profiling features including **Profile all requests** (POST, Ajax, API calls)
33
+
*[Chrome extension](https://docs.blackfire.io/integrations/browsers/chrome) — single-page profiling works, but **Profile all requests** is unavailable (see below)
34
+
35
+
### Chrome limitation
36
+
37
+
:::{warning}
38
+
Chrome's Manifest V3 restricts extensions from modifying outgoing request headers, which breaks the **Profile all requests** feature. Chrome can only profile the initial page load — it cannot capture follow-up POST requests, Ajax calls, or API requests within a session. Single-page profiling still works normally.
39
+
40
+
If your workflow relies on profiling all requests in a session, **use Firefox** where this feature remains fully supported. For more details, see [Announcing changes to the "Profile all requests" feature on Chrome](https://blog.blackfire.io/announcing-changes-to-the-profile-all-requests-feature-on-chrome.html) on the Blackfire blog.
Further information on customizing or extending an environment is forthcoming. For now, this section is limited to very simple and somewhat common customizations.
3
+
## Version Customization via `.env`
4
4
5
5
To configure your project with a non-default PHP version, add the following to the project's `.env` file and run `warden env up` to re-create the affected containers:
6
6
7
7
PHP_VERSION=7.2
8
8
9
-
The versions of MariaDB, Elasticsearch, Varnish, Redis, NodeJS and Composer may also be similarly configured using variables in the `.env` file:
9
+
The versions of Elasticsearch, Varnish, Redis, NodeJS and Composer may also be similarly configured using variables in the `.env` file:
10
10
11
-
*`MARIADB_VERSION`
12
11
*`ELASTICSEARCH_VERSION`
13
12
*`REDIS_VERSION`
14
13
*`VALKEY_VERSION`
@@ -17,24 +16,93 @@ The versions of MariaDB, Elasticsearch, Varnish, Redis, NodeJS and Composer may
17
16
*`NODE_VERSION`
18
17
*`COMPOSER_VERSION`
19
18
19
+
## Database
20
+
21
+
Warden supports both **MariaDB** (default) and **MySQL** as the database engine. The distribution and version are controlled via two environment variables in your project's `.env` file:
22
+
23
+
*`MYSQL_DISTRIBUTION` — set to `mariadb` (default) or `mysql`
24
+
*`MYSQL_DISTRIBUTION_VERSION` — the image tag/version to use
25
+
26
+
For example, to use MariaDB 11.4:
27
+
28
+
MYSQL_DISTRIBUTION=mariadb
29
+
MYSQL_DISTRIBUTION_VERSION=11.4
30
+
31
+
To use MySQL 8.4 instead:
32
+
33
+
MYSQL_DISTRIBUTION=mysql
34
+
MYSQL_DISTRIBUTION_VERSION=8.4
35
+
36
+
:::{note}
37
+
Drupal and CakePHP environments use `DB_DISTRIBUTION` and `DB_DISTRIBUTION_VERSION` instead of the `MYSQL_` prefix. The values and behavior are the same.
38
+
:::
39
+
40
+
After changing the database distribution or version, run `warden env up` to re-create the database container.
41
+
42
+
:::{warning}
43
+
Switching distributions (e.g. from MariaDB to MySQL) is **not** a drop-in replacement for existing data volumes. If you change the distribution on an existing environment, you should export your database first, remove the db volume (`warden env down -v`), and re-import after the new container is running.
44
+
:::
45
+
20
46
Start of some environments could be skipped by using variables in `.env` file:
21
47
22
48
*`WARDEN_DB=0`
23
49
*`WARDEN_REDIS=0`
24
50
*`WARDEN_VALKEY=0`
25
51
26
-
## Docker Specific Customizations
27
-
To override default docker settings, add a custom configuration file in your project root
28
-
folder: `/.warden/warden-env.yml`
29
-
This file will be merged with the default environment configuration.
30
-
One example for a use case is [the setup of multiple domains](https://docs.warden.dev/configuration/multipledomains.html?highlight=warden%20env%20yml#multiple-domains).
52
+
## Docker Compose Overrides
31
53
32
-
## PHP Specific Customizations
33
-
To override default php settings, follow the docker customization above and include your custom `php.ini` file.
34
-
In this case the `warden-env.yml` should look like this:
54
+
For customizations beyond `.env` variables, Warden supports per-project Docker Compose override files. Create a `.warden/warden-env.yml` file in your project root to override or extend the default service configuration.
55
+
56
+
This file is a standard Docker Compose YAML partial. Warden loads it **after** all built-in service definitions, giving it the highest merge precedence — any service, volume, label, or environment variable defined here will override the defaults.
57
+
58
+
:::{tip}
59
+
Preview the fully merged Docker Compose configuration at any time with:
60
+
61
+
warden env config
62
+
:::
63
+
64
+
### OS-Specific Overrides
65
+
66
+
In addition to `.warden/warden-env.yml`, Warden also loads OS-specific override files if they exist:
67
+
68
+
*`.warden/warden-env.darwin.yml` — applied only on **macOS**
69
+
*`.warden/warden-env.linux.yml` — applied only on **Linux**
70
+
71
+
This is useful for platform-specific volume mount options or performance tuning.
72
+
73
+
### Custom Docker Image
74
+
75
+
To use a custom PHP-FPM image (e.g., with pre-installed extensions or from a private registry):
76
+
77
+
```yaml
78
+
services:
79
+
php-fpm:
80
+
image: my-registry/custom-php:8.3
81
+
php-debug:
82
+
image: my-registry/custom-php:8.3-debug
83
+
```
84
+
85
+
### Adding Extra Services
86
+
87
+
You can add services not included by default. For example, to add Adminer with Traefik routing:
There you can specify a custom Nginx configuration which will be included following the `.conf` files within the `/etc/nginx/available.d` directory: `include /etc/nginx/default.d/*.conf`
74
148
149
+
## Advanced: Project-Level Environment Partials
150
+
151
+
Beyond `.warden/warden-env.yml`, Warden supports a more granular override mechanism through project-level environment partial directories. For each service partial (e.g., `php-fpm`, `nginx`, `db`), Warden searches the following locations in order:
Copy file name to clipboardExpand all lines: environments/magento2.md
+1-1Lines changed: 1 addition & 1 deletion
Display the source diff
Display the rich diff
Original file line number
Diff line number
Diff line change
@@ -234,7 +234,7 @@ In addition to the below manual process, there is a `Github Template available f
234
234
:::
235
235
236
236
:::{note}
237
-
Use of 2FA is mandatory on Magento ``2.4.x`` and setup of 2FA should be skipped when installing ``2.3.x`` or earlier. Where 2FA is setup manually via UI upon login rather than using the CLI commands above, the 2FA configuration email may be retrieved from `the Mailhog service <https://mailhog.warden.test/>`_.
237
+
Use of 2FA is mandatory on Magento ``2.4.x`` and setup of 2FA should be skipped when installing ``2.3.x`` or earlier. Where 2FA is setup manually via UI upon login rather than using the CLI commands above, the 2FA configuration email may be retrieved from [the webmail service](https://webmail.warden.test/).
Copy file name to clipboardExpand all lines: environments/types.md
+1-1Lines changed: 1 addition & 1 deletion
Display the source diff
Display the rich diff
Original file line number
Diff line number
Diff line change
@@ -96,7 +96,7 @@ Files are currently mounted using a delegated mount on macOS and natively on Lin
96
96
97
97
## Commonalities
98
98
99
-
In addition to the above, each environment type (with the exception of the `local` type) come with PHP setup to use `mhsendmail` to ensure outbound email does not inadvertently leave your network and to support simpler testing of email functionality. Mailhog may be accessed by navigating to [https://mailhog.warden.test/](https://mailhog.warden.test/) in a browser.
99
+
In addition to the above, each environment type (with the exception of the `local` type) come with PHP setup to use `mhsendmail` to ensure outbound email does not inadvertently leave your network and to support simpler testing of email functionality. The webmail interface may be accessed by navigating to [https://webmail.warden.test/](https://webmail.warden.test/) in a browser.
100
100
101
101
Where PHP is specified in the above list, there should be two `fpm` containers, `php-fpm` and `php-debug` in order to provide Xdebug support. Use of Xdebug is enabled by setting the `XDEBUG_SESSION` cookie in your browser to direct the request to the `php-debug` container. Shell sessions opened in the debug container via `warden debug` will also connect PHP process for commands on the CLI to Xdebug.
0 commit comments