diff --git a/environments/customizing.md b/environments/customizing.md index d5a936c..7143af6 100644 --- a/environments/customizing.md +++ b/environments/customizing.md @@ -1,6 +1,6 @@ # Customizing An Environment -Further information on customizing or extending an environment is forthcoming. For now, this section is limited to very simple and somewhat common customizations. +## Version Customization via `.env` 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: @@ -23,18 +23,60 @@ Start of some environments could be skipped by using variables in `.env` file: * `WARDEN_REDIS=0` * `WARDEN_VALKEY=0` -## Docker Specific Customizations -To override default docker settings, add a custom configuration file in your project root -folder: `/.warden/warden-env.yml` -This file will be merged with the default environment configuration. -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). +## Docker Compose Overrides -## PHP Specific Customizations -To override default php settings, follow the docker customization above and include your custom `php.ini` file. -In this case the `warden-env.yml` should look like this: +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. + +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. + +:::{tip} +Preview the fully merged Docker Compose configuration at any time with: + + warden env config +::: + +### OS-Specific Overrides + +In addition to `.warden/warden-env.yml`, Warden also loads OS-specific override files if they exist: + * `.warden/warden-env.darwin.yml` — applied only on **macOS** + * `.warden/warden-env.linux.yml` — applied only on **Linux** + +This is useful for platform-specific volume mount options or performance tuning. + +### Custom Docker Image + +To use a custom PHP-FPM image (e.g., with pre-installed extensions or from a private registry): + +```yaml +services: + php-fpm: + image: my-registry/custom-php:8.3 + php-debug: + image: my-registry/custom-php:8.3-debug +``` + +### Adding Extra Services + +You can add services not included by default. For example, to add Adminer with Traefik routing: + +```yaml +services: + adminer: + image: adminer:latest + labels: + - traefik.enable=true + - traefik.http.routers.${WARDEN_ENV_NAME}-adminer.rule=Host(`adminer.${TRAEFIK_DOMAIN}`) + - traefik.http.routers.${WARDEN_ENV_NAME}-adminer.tls=true ``` -version: "3.5" + +After adding this and running `warden env up -d`, Adminer will be accessible at `https://adminer..test`. + +## PHP Specific Customizations + +To override default PHP settings, mount a custom `php.ini` file via `.warden/warden-env.yml`: + +```yaml services: php-fpm: volumes: @@ -43,14 +85,18 @@ services: volumes: - ./.warden/php/zz-config.ini:/etc/php.d/zz-config.ini ``` + Now add the referenced `.warden/php/zz-config.ini` file with your wanted changes. For example you could change the error reporting value: -``` + +```ini error_reporting=(E_ALL ^ E_DEPRECATED) ``` + The config file will be merged with the default `01-php.ini` resp. override the values included there. The default values are the following: -``` + +```ini date.timezone = UTC max_execution_time = 3600 max_input_vars = 10000 @@ -60,22 +106,51 @@ post_max_size = 25M session.auto_start = Off upload_max_filesize = 25M ``` + ## Nginx Specific Customizations -To override the default nginx configuration of your project, add a new file -`.warden/warden-env.yml` to your project root with the following content: -``` -version: "3.5" + +To override the default nginx configuration of your project, add the following to `.warden/warden-env.yml`: + +```yaml services: nginx: volumes: - ./.warden/nginx/custom.conf:/etc/nginx/default.d/custom.conf ``` + 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` +## Advanced: Project-Level Environment Partials + +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: + + 1. Built-in includes: `/environments/includes/` + 2. Built-in type-specific: `/environments//` + 3. User home includes: `~/.warden/environments/includes/` + 4. User home type-specific: `~/.warden/environments//` + 5. **Project includes: `.warden/environments/includes/`** + 6. **Project type-specific: `.warden/environments//`** + +Files at each location use suffixes: `.base.yml` (all platforms), `.darwin.yml` (macOS), `.linux.yml` (Linux). + +For example, to override just the `php-fpm` partial for a Magento 2 project, create: + + .warden/environments/includes/php-fpm.base.yml + +This is loaded in addition to (and after) the built-in `php-fpm.base.yml`, so Docker Compose merge semantics apply. + +:::{note} +The `.warden/warden-env.yml` file is still loaded **after** all partials, so it always has the final say. +::: + +## Multiple Domains + +For configuring multiple top-level domains, see [Multiple Domains](../configuration/multipledomains.md). + ## Magento 1 Specific Customizations -If you use a `modman` structure, initialize the environment in your project path. -The `.modman` folder and the corresponding `.basedir` file will be recognized and set up automatically. +If you use a `modman` structure, initialize the environment in your project path. +The `.modman` folder and the corresponding `.basedir` file will be recognized and set up automatically. ## Magento 2 Specific Customizations