Skip to content

Drupal stack containers

SSH and Cron containers

For Wodby environments we additionally spin up copies of PHP services with overridden commands to run cron and ssh daemons. All environment variables added to PHP-FPM service will be automatically passed to SSHd and Crond services.

Nginx

Do not gzip pages in Drupal

We already gzip content on Nginx side and it works faster. Having double gzip may cause issues.

Restarting nginx as default user:

sudo nginx -s reload

PHP endpoints

For security reasons, default nginx config allows executing limited php endpoints. This is how you can add additional php endpoints:

  1. Add *.conf file to your codebase with locations definition, example:
    location = /custom-php-endpoint.php {
        fastcgi_pass php;
    }
    
  2. In nginx service configuration set new environment variable NGINX_SERVER_EXTRA_CONF_FILEPATH to your *.conf file (e.g. /var/www/html/drupal.conf). It will be included at the end of /etc/nginx/conf.d/drupal.conf
  3. Restart the service

Alternatively, you can replace your HTTP server to Apache (not recommended) that has less strict rules.

XML endpoints

By default nginx config requests Drupal backend when rss.xml or sitemap.xml requested. If you want to add another XML endpoint generated by Drupal just set environment variable NGINX_ALLOW_XML_ENDPOINTS to any value and restart the service.

Custom config

If the default drupal config and available environment variables are not enough for your customizations you can replace the config with your own:

  1. Copy /etc/nginx/conf.d/drupal.conf to your codebase, adjust to your needs
  2. Deploy code with your config file
  3. Add new environment variable NGINX_CONF_INCLUDE for nginx service, the value should the path to your *.conf file (e.g. /var/www/html/nginx.conf

Files proxy

You can proxy all requests to files to (similar to what drupal module stage_file_proxy does) by adding the environment variable NGINX_DRUPAL_FILE_PROXY_URL to URL of your Drupal instance with files, e.g. http://example.com

Mod pagespeed

Nginx comes with mod_pagespeed which is disabled by default. To enable it add NGINX_PAGESPEED=on environment variable to Nginx service.

Apache

Restarting apache as default user:

sudo httpd -k restart

PHP

  • PHP can be configured with the following environment variables
  • Available php extensions
  • Composer pre-installed with a default global package hirak/prestissimo:^0.3 to download dependencies in parallel

Files directory permissions

Public files directory (symlink to /mnt/files/public) that used for uploads owned by www-data user (PHP-FPM user) by default and the default container user (wodby) has no writing permissions. So if you run a command that creates files in a public directory you will get insufficient permissions error. You can fix this problem by giving writing permissions for files directory to the owner's group (user wodby is a member of www-data group) by using one of the helper scripts:

sudo files_chmod /mnt/files/public

For mode details about users and permissions in PHP container see https://github.com/wodby/php#users-and-permissions

Environment variables

Variables availability

Environment variables provided by Wodby are always available in PHP even if PHP_FPM_CLEAR_ENV set to no.

In addition to global environment variables, we provide the following variables in PHP container that you can use in your post-deployment scripts or settings files:

Variable Description
$APP_ROOT /var/www/html by default
$HTTP_ROOT e.g. /var/www/html/web
$CONF_DIR /var/www/conf by default
$WODBY_APP_NAME My app
$WODBY_HOST_PRIMARY example.com
$WODBY_URL_PRIMARY http://example.com
$WODBY_HOSTS [ "example.com", "dev.example.org.wod.by" ]

Deprecated variables:

Variable Instead use
$WODBY_APP_ROOT $APP_ROOT
$WODBY_APP_DOCROOT $HTTP_ROOT
$WODBY_CONF $CONF_DIR
$WODBY_DIR_CONF $CONF_DIR

Drupal-specific

Additionally, variable $DRUPAL_SITE (previous deprecated name $WODBY_APP_SUBSITE) contains Drupal site directory, e.g. default.

WARNING

Some environment variables used by PHP may be overridden in wodby.settings.php file

Xdebug (remote)

Follow these steps to debug your application instance remotely with xdebug:

  1. Enable xdebug for your instance from [Instance] > Stack > Settings
  2. Set up forwarding for xdebug: copy Xdebug SSH tunnel command from [Instance] > Stack > PHP and run on your local machine
  3. Make sure you have your IDE xdebug listener running on port 9000
  4. Start debugging in IDE
  5. Start your browser debug helper plugin (Chrome or Firefox) and open the page you want to debug

Xdebug (local)

Debugging web requests

  1. Uncomment these lines for PHP service in your docker-compose file
    PHP_XDEBUG: 1                 
    PHP_XDEBUG_DEFAULT_ENABLE: 1
    
  2. Restart containers (make)
  3. Start debugging in IDE
  4. Start your browser debug helper plugin (Chrome or Firefox) and open the page you want to debug. Alternatively, enable auto start by adding PHP_XDEBUG_REMOTE_AUTOSTART=1

Debugging CLI requests

  1. Enable Xdebug as described in the previous section
  2. Uncomment the following environment variables for PHP service in your composer file
    PHP_XDEBUG_REMOTE_CONNECT_BACK: 0    
    PHP_IDE_CONFIG: serverName=my-ide
    
  3. Configure your IDE
  4. Perform configuration as described below depending on your OS and Docker version:
Linux, Docker
  1. Uncomment PHP_XDEBUG_REMOTE_HOST: 172.17.0.1 for PHP service (if you have docker 18.03+ you can specify host.docker.internal instead of the IP address)
  2. Restart containers (make)
macOS, Docker
  1. Uncomment PHP_XDEBUG_REMOTE_HOST: 10.254.254.254 for PHP service (just a random IP that very likely won't be used by anything else).
  2. Restart containers (make)
  3. You also need to have loopback alias with IP from above. You need this only once and that settings stays active until logout or restart:
    sudo ifconfig lo0 alias 10.254.254.254
    
  4. To add the loopback alias after a reboot, add the following contents to /Library/LaunchDaemons/docker4drupal.loopback.plist:
    <plist version="1.0">
      <dict>
        <key>Label</key>
        <string>Default Loopback alias</string>
        <key>ProgramArguments</key>
        <array>
          <string>/sbin/ifconfig</string>
          <string>lo0</string>
          <string>alias</string>
          <string>10.254.254.254</string>
          <string>netmask</string>
          <string>255.255.255.0</string>
        </array>
        <key>RunAtLoad</key>
        <true/>
      </dict>
    </plist>
    
Windows
  1. Uncomment PHP_XDEBUG_REMOTE_HOST: 10.0.75.1 for PHP service (default IP of Docker NAT).
  2. Restart containers (make)
  3. Allow listen connection for your IDE in Windows Firewall > Allow an app ..

Also, you might need to add the following lines to your hosts file (see related github issue):

0.0.0.0         localhost
10.0.75.1       localhost

IDE configuration

You must additionally configure your IDE to debug CLI requests.

PHPStorm
  1. Open Run > Edit Configurations from the main menu, choose Defaults > PHP Web Page in the left sidebar
  2. Click to [...] to the right of Server and add a new server
    • Enter name my-ide (as specified in PHP_IDE_CONFIG)
    • Enter any host, it does not matter
    • Check Use path mappings, select path to your project and enter /var/www/html in the right column (Absolute path on the server)
  3. Choose newly created server in "Server" for PHP Web Page
  4. Save settings

NewRelic

You can add NewRelic APM monitoring for PHP by adding environment variables PHP_NEWRELIC_ENABLED=1 and PHP_NEWRELIC_LICENSE with your license number to PHP-FPM container. Application name will be automatically set to [Wodby Application Name] - [Wodby Instance Name], if you want to change it, use PHP_NEWRELIC_APPNAME.

Profiling

You can profile your PHP application either via Xdebug traces (+Webgrind) or Tideways XHProf extensions.

PHPUnit

  1. Inside your drupal/core directory, copy the file phpunit.xml.dist and rename it to phpunit.xml
  2. Open that file and make sure that you update SIMPLETEST_BASE_URL to http://nginx
  3. In order to make sure that your DB connection is working as well, update SIMPLETEST_DB to mysql://drupal:drupal@mariadb/drupal

Drush

PHP container comes with pre-installed drush and drush launcher. Drush launcher will help you use drush that comes with your project without specifying the full path to it.

Drupal Console

PHP container comes with installed drupal console launcher (not the same as drupal console), the launcher used to be able run drupal console without specified the full path to it. Please note that starting Drupal Console ~1.0 you have to install it manually (via composer) per project.

Crond

A duplicate of the main PHP container runs with crond (instead of FPM). You can customize crontab from [Instance] > Stack > Settings page.

SSHd

A duplicate of PHP container runs with SSH daemon (instead of FPM). You can find access information on [Instance] > Stack > SSH

Public SSH keys from your Wodby profile will be added automatically for all users that have access to an instance.

Mailhog

If Mailhog service enabled and chosen as Mail delivery service at [Instance] > Stack > Settings all outbound email will be caught by the Mailhog. You can view and release these emails from Mailhog UI, the URL can be found from Domains tab. When release specify opensmtpd in SMTP server field if you want to release emails to the default Mail transfer agent (OpenSMTPD).

OpenSMTPD

See OpenSMTPD stack documentation.

MariaDB

See MariaDB stack documentation.

Node.js

Light-weight node.js container to help you build your application's frontend. The containers comes without any global pre-installed packages, you can add them by running yarn global add PACKAGE or by running yarn in a directory with your package.json file.

Drupal Node.js

Drupal node is a container with a server app for the Node.js Integration Drupal module. You can configure Node.js via environment variables that listed at https://github.com/wodby/drupal-node

Usage:

  1. Install Node.js Integration Drupal module on your site
  2. Visit the Node.js configuration page under the Configuration menu, and enter the connection information for your Node.js server application. Set host to node (or drupal-node for local environment) and service key can be found on [Instance] > Stack > Node.js

Solr

See Solr for Drupal stack documentation.

Memcached

You can check the status of memcached and its hits by running the following command.

watch "echo stats | nc 127.0.0.1 11211"

Redis

Drupal 8

Install redis module and enable redis integration under [Instance] > Cache > Settings page of Wodby dashboard to use it as an internal cache storage for Drupal. All required configuration already provided in wodby.settings.php file.

Drupal 7

Install redis module to use it as an internal cache storage for Drupal. All required configuration already provided in wodby.settings.php file.

Redis stack documentation

Varnish

Varnish ignores the following GET parameters for cache id generation:

utm_source
utm_medium
utm_campaign
utm_content
gclid
cx
ie
cof
siteurl

For more details see Varnish stack documentation

Drupal 8

Read this article to learn how to use Varnish with Drupal 8.

Drupal 7

  1. Install and enable varnish module (use the dev version). All required configuration for this module already provided in wodby.settings.php file
  2. Go to Home » Administration » Configuration » Development page of Drupal website and
  3. Check Cache pages for anonymous users
  4. Check Compress cached pages. Check Aggregate and compress CSS files. Check Aggregate JavaScript files. Also, we recommend to install expire module to configure auto purge of pages when some content has been updated. After installation go to Home » Administration » Configuration » System and select External expiration at the "Module status" tab.

Rsyslog

Rsyslog can be used to stream your applications logs (watchdog). It's similar to using syslog, however there's no syslog in PHP container. Rsyslog will stream all incoming logs to a container output.

Here how you can use it with Monolog:

  1. Install monolog module. Make sure all dependencies being downloaded
  2. Add new handler at monolog/monolog.services.yml:
    monolog.handler.rsyslog:
      class: Monolog\Handler\SyslogUdpHandler
      arguments: ['rsyslog']
    
  3. Rebuild cache (drush cr)
  4. Use rsyslog handler for your channels
  5. Find your logs in rsyslog container output

Read Logging in Drupal 8 to learn more.

Blackfire

You can profile your application via blackfire.io by following the next steps:

  • Enable blackfire probe extension by adding the environment variable PHP_BLACKFIRE=1 to PHP container
  • Enable blackfire agent service in your stack
  • Add environment variables BLACKFIRE_SERVER_ID and BLACKFIRE_SERVER_TOKEN to blackfire agent service with appropriate values from your blackfire.io profile
  • Install blackfire companion extension for Chrome or Firefox
  • Start profiling your app via the extension and see data from blackfire.io dashboard

Fore more details please refer to the blackfire official documentation

Webgrind

Webgrind allows you view and analyze Xdebug profiler output and generate call graphs for visualisation. To use Webgrind first enable Xdebug profiler by adding the following environment variables to your PHP container:

PHP_XDEBUG: 1
PHP_XDEBUG_PROFILER_ENABLE: 1
PHP_XDEBUG_PROFILER_ENABLE_TRIGGER: 1
PHP_XDEBUG_PROFILER_ENABLE_TRIGGER_VALUE: 1

Add XDEBUG_PROFILE=1 param to GET or POST request (or set a cookie) you want to profile. Xdebug will generate profile files in /mnt/files/xdebug/profiler. Click Update in Webgrind to access the new information. See https://xdebug.org/docs/profiler to learn more about xdebug profiling.

IMPORTANT

Xdebug profiling significantly decreases performance and increases resources usage. DO NOT USE it on Production servers.