Service type
PHP (Drupal 11) service
PHP runtime service for Drupal websites, with source builds and links to shared files, caching, and search services.
Use it as a versioned stack building block that can build from source, plug into CI/CD, and connect to external providers without hardcoding secrets into the codebase.
Why teams use this service
Technical profile
Review versions, ports, source, and packaging.
Stacks that use it
See where this service fits in ready-made stacks.
Source builds and CI/CD
Start from a compatible boilerplate, use Wodby CI, and publish images cleanly.
Runtime wiring and defaults
See ports, links, storage, configs, and runtime behavior.
On Wodby
How PHP (Drupal 11) runs on Wodby
Linked services
Links to other services reach the application as environment variables. Read them in code; do not hardcode hosts or credentials.
| Link | Variables |
|---|---|
| Database (MariaDB, MySQL or PostgreSQL) | DB_HOST, DB_PORT, DB_NAME (also DB_DATABASE), DB_USERNAME, DB_PASSWORD, DB_DRIVER (also DB_CONNECTION) |
MSMTP_HOST, MSMTP_PORT | |
| OpenTelemetry Collector | OTEL_EXPORTER_OTLP_ENDPOINT, OTEL_EXPORTER_OTLP_PROTOCOL (http/protobuf), OTEL_EXPORTER_OTLP_HEADERS (the Collector's ingest token), OTEL_PHP_AUTOLOAD_ENABLED (true) |
Mail needs no code: PHP's mail() is delivered through the linked mail service. An SMTP library or credentials in the codebase are not required.
A variable is present only while its link exists and the linked service is enabled.
The opentelemetry extension is enabled in the image. To send traces, add the OpenTelemetry PHP SDK, the OTLP exporter and an HTTP client with Composer (open-telemetry/sdk, open-telemetry/exporter-otlp and php-http/guzzle7-adapter), plus auto-instrumentation packages for the framework if wanted; with the link, the SDK configures itself from the variables above. Set OTEL_SERVICE_NAME to name the application in traces. Without the link the SDK stays off.
Generated configuration
On every start the container writes $CONF_DIR/wodby.settings.php (normally /var/www/conf/wodby.settings.php), a $wodby array with the environment's hosts, the files directory and the linked database's connection details. Framework services built on this one extend it and include it for the application. It is outside the codebase and rewritten on start: never edit it or copy its values into the repository. In a plain PHP application, read the variables above.
PHP settings
PHP and PHP-FPM are configured through environment variables on the service, such as PHP_MEMORY_LIMIT, PHP_MAX_EXECUTION_TIME or PHP_FPM_PM_MAX_CHILDREN, not through a php.ini in the repository. A change applies with the next deployment of the service.
Environment
WODBY_HOSTSis a JSON array of the environment's hosts;WODBY_PRIMARY_HOSTandWODBY_PRIMARY_URLare the canonical ones for links generated outside a request.WODBY_ENV_TYPEtells a development environment from a production-like one.
In a development workspace
- The code is served from the checkout as it is on disk. PHP checks files for changes on every request, so an edit needs no restart.
- PHP-FPM handles requests as
wodby, the user that owns the checkout, so it reads what the developer can read and the files it writes stay editable over SSH. - Dependencies are installed by workspace setup with
composer install;/vendor/is kept out of Git status. - A change to variables or linked services still needs a deployment of the environment.
Drupal on Wodby
What Wodby sets up for a Drupal application on this service, in addition to the PHP service it is based on. Check it before changing settings.php, connecting Drupal to a cache or search service, or moving the files and configuration directories. Adding a second copy of this configuration to the codebase is the usual mistake.
What Wodby generates
The Drupal PHP container writes two files on every start, from its environment variables:
$CONF_DIR/wodby.settings.php(normally/var/www/conf/wodby.settings.php)$CONF_DIR/wodby.sites.php
They are outside the codebase and are rewritten on each start, so never edit them and never copy their values into the repository. sites/<site>/settings.php includes the first one in a block marked // Generated by Wodby., appended at the end of the file by the build or by workspace setup. Keep that block, and keep it after the project's own settings. With a site directory other than default, sites/sites.php includes the second file, which maps the environment's hosts to that site.
Read the generated file to see exactly what applies to this environment. It holds passwords: quote setting names, not secret values.
What it configures
| Area | What Wodby sets | From |
|---|---|---|
| Database | $databases['default']['default'] host, port, name, user, password, driver | DB_*, set by the linked database |
| Hosts | trusted_host_patterns for every host of the environment | WODBY_HOSTS |
| Proxy | reverse_proxy and reverse_proxy_addresses | request, DRUPAL_REVERSE_PROXY_ADDRESSES |
| Hash salt | hash_salt, when the project sets none | DRUPAL_HASH_SALT |
| Files | public sites/<site>/files, private $FILES_DIR/private, temporary /tmp | FILES_DIR |
| Config sync | config_sync_directory under $FILES_DIR/config/, when the project sets none | DRUPAL_FILES_SYNC_SALT |
| Cache | Redis connection and cache backend, under the conditions below | REDIS_* |
| Search | Search API Solr server credentials | SOLR_CLOUD_* |
The database, file paths and trusted hosts are set by Wodby whatever the project's settings say. The hash salt and the config sync directory are only defaults: a project that keeps configuration in Git sets its own config_sync_directory above the Wodby block, and Wodby leaves it alone.
sites/<site>/files is a link to the files volume ($FILES_DIR/public). Uploaded files live on that volume, not in the codebase and not in the image.
Redis or Valkey cache
The connection and the cache backend are configured by Wodby when all of these hold:
- The stack's Redis or Valkey service is enabled and linked to the Drupal PHP service.
REDIS_HOSTis then set in the container. - The
drupal/redismodule is in the codebase (composer require drupal/redis) undermodules/contribormodules. - The Drupal PHP service has the environment variable
DRUPAL_ENABLE_REDIS_CACHEset to a non-empty value, for example1.
Then the generated settings point redis.connection at the service with the PhpRedis interface, make Redis the default cache backend and load the module's example.services.yml. Do not add Redis settings to settings.php. What is left for the project is to enable the module (drush en redis) and rebuild caches.
A missing condition is the usual reason "Redis is not used": check REDIS_HOST, the module directory and DRUPAL_ENABLE_REDIS_CACHE before changing anything else.
Solr
With a linked Solr service, Wodby overrides the username and password of one Search API Solr server in configuration: the server whose machine name equals SOLR_CLOUD_SERVER, which is the Solr service's host name in the environment (normally solr). Give the Search API server that machine name, and do not store the password in exported configuration or in settings.php. The rest of the server's configuration, such as its connector, host and collection, belongs to the project's own Drupal configuration.
Changing what is wired
Service connections come from the environment's services and their links, not from code:
- To add a cache or search service, enable it in the environment's services and make sure it is linked to this service, then deploy.
- A variable such as
DRUPAL_ENABLE_REDIS_CACHEis set on this service in the environment. It reaches the container, and the generated settings, with the next deployment of the service. - Code changes (
composer require, enabling a module, exported configuration) go through the repository as usual.
In a development workspace
A workspace runs the same image against the live checkout, with the same generated files and the same variables. Differences that matter:
- Workspace setup appends the include to the checkout's
settings.phpin a form that is safe to commit: it includes the file only where it exists. - The checkout's
sites/<site>/filesbecomes a link to the files volume. Setup refuses when that directory is tracked by Git or not ignored; fix the repository instead of working around it. - The generated files are rewritten when the container starts. After enabling a service or changing a variable, deploy the environment and check
$CONF_DIR/wodby.settings.phpagain. drushandcomposerrun from the checkout with the same environment as web requests.
Check the result
Confirm against the running environment, not the code alone:
drush statusshows the database connection.drush php:eval 'var_export(\Drupal\Core\Site\Settings::get("cache"));'shows the cache backend in use.- The Search API server page, or
drush search-api:server-list, shows whether Solr is reachable.
Overview
Technical profile and packaging
Versions
Built on top
Source repository
Public Helm chart
Ports and protocols
Labels
Persistent volumes
Stacks
Use it inside ready-made stacks or your own
CI/CD
Build from source and ship changes without extra glue work
Drupal CMS
Start from a working boilerplate instead of wiring the build process from scratch.
wodby/drupal-cms-templateVanilla Drupal
Start from a working boilerplate instead of wiring the build process from scratch.
wodby/drupal-vanillaGit providers
Connect repositories from supported Git providers when this service should build from your own codebase.
CI providers
Wodby CI is the default path, but external CI providers can fit the same build and release workflow when that suits your team better.
Container registries
Keep built images in Wodby Registry by default or store them in another registry without changing how the service is built.
Keep secrets and variables outside the codebase
Attach provider credentials and environment variables at the platform level so the build and runtime do not depend on hardcoded secrets.
Runtime wiring
Reuse connectivity, storage, and runtime defaults
Endpoints
Volumes
Settings
Cron schedules
Lifecycle actions
Service links
These links define which other services can connect to PHP (Drupal 11) when it is used inside a stack.
db
Eligible linked services
files
Eligible linked services
solr
Eligible linked services
redis
Eligible linked services
sendmail
Eligible linked services
otel
Eligible linked services