Project configuration¶

How to configure a Drupal project for preview environments. Run druploy setup from your project root to scaffold these files automatically.

File structure¶

After running druploy setup, your project will have the following new files:

your-project/
├── druploy.yml                          # Preview configuration
├── web/sites/default/                   # (or docroot/)
│   ├── settings.php                     # Modified: include snippet added
│   └── settings.druploy.php             # Created: per-project overrides
└── scripts/druploy/
    ├── new/deploy.sh                    # Runs on first deploy
    └── update/deploy.sh                 # Runs on code updates

`druploy.yml`¶

This file lives in the project root and defines how preview environments are built. All fields are optional — sensible defaults are used when omitted.

# PHP version for the preview container.
# Supported: 8.1, 8.2, 8.3, 8.4
php_version: "8.3"

# Database engine and version (same format as DDEV).
# Examples:
#   mysql:5.7    (≈ mariadb:10.3)
#   mysql:8.0    (≈ mariadb:10.6)
#   mysql:8.4    (≈ mariadb:11.4)
#   mariadb:10.6 (≈ mysql:8.0)
#   mariadb:11.4 (≈ mysql:8.4)
database: mysql:8.0

# Document root relative to the project root.
# Auto-detected if not set (checks web/ then docroot/).
docroot: web

# Optional services. Set a version to enable, false to disable.
# When enabled, PREV_*_HOST env vars are set automatically.
# Note: redis and valkey are mutually exclusive (valkey wins).
redis: false          # e.g. "7", "6"
valkey: false         # e.g. "8", "7" (Redis-compatible fork)
solr: false           # e.g. "9", "8"

# Solr configset — path relative to project root with schema.xml etc.
# Generate with: drush search-api-solr:get-server-config
# solr_configset: "etc/solr"

# Custom environment variables injected into the PHP container.
# Available in settings.druploy.php via getenv().
# env:
#   APP_ENV: preview
#   MY_CUSTOM_VAR: some-value

# Domain aliases — additional subdomains that route to this preview.
# Each prefix becomes {prefix}--{preview-domain}.druploy.dev
# Useful for multi-site setups. Available as PREV_DOMAIN_ALIASES env var.
# domain_aliases:
#   - admin
#   - fr
#   - de

# Drush URI — custom URI for drush --uri flag (used in drush uli, etc).
# Can be a domain alias name (e.g. "admin") or a full URL.
# If not set or false, the preview URL is used automatically.
# drush_uri: admin

# LiteSpeed Cache — enable the built-in OLS cache module.
# Requires the Drupal "lite_speed_cache" module.
# litespeed_cache: true

# Deploy scripts — executed inside the PHP container.
# Paths are relative to the project root.
# Set to false or omit to skip.
deploy:
  new: scripts/druploy/new/deploy.sh
  update: scripts/druploy/update/deploy.sh

Defaults when `druploy.yml` is missing¶

Option	Default
PHP version	`8.3`
Database	`mysql:8.0`
Docroot	`web` (auto-detected)
Redis / Valkey	disabled
Solr	disabled
LiteSpeed Cache	disabled
Domain aliases	none
Deploy scripts	none

`settings.php` include¶

The druploy setup command appends this snippet at the end of your settings.php. It conditionally loads preview-specific settings only when running inside a preview environment.

// Preview environment settings.
if (getenv('PREV_IS_PREVIEW')) {
  include __DIR__ . '/settings.druploy.php';
}

Note

PREV_IS_PREVIEW is only set inside preview containers, so this snippet has no effect in your local or production environments.

`settings.druploy.php`¶

This file is managed by you for custom overrides. The internal preview configuration (database connection, file paths, trusted host patterns) is handled automatically by settings.druploy.internal.php, which is generated by the deployer and included before this file.

<?php

/**
 * @file
 * Preview environment overrides.
 *
 * Loaded after the internal preview configuration, which sets up
 * database, file paths, and trusted host patterns automatically.
 */

// Example: disable CSS/JS aggregation in previews.
// $config['system.performance']['css']['preprocess'] = FALSE;
// $config['system.performance']['js']['preprocess'] = FALSE;

// Example: enable stage_file_proxy pointing to production.
// $config['stage_file_proxy.settings']['origin'] = 'https://example.com';

You can extend this file with any project-specific overrides — disabling caches, enabling stage_file_proxy, tweaking trusted host patterns, etc.

Deploy scripts¶

Deploy scripts run inside the PHP container after the environment is ready. There are two phases:

new — First deployupdate — Code updates

Runs after database import and file setup. Typically runs drush deploy (updatedb + config-import + cache-rebuild).

#!/usr/bin/env bash
set -euo pipefail

DRUSH="vendor/bin/drush"

echo "Running new preview deploy script..."

$DRUSH deploy

echo "Deploy complete."

Runs when new commits are pushed to the MR. Same as above but without re-importing database or files.

#!/usr/bin/env bash
set -euo pipefail

DRUSH="vendor/bin/drush"

$DRUSH deploy

Per-preview overrides¶

You can create preview-specific scripts that override the default:

scripts/druploy/new/mr-123-deploy.sh

This script will run instead of the default deploy.sh for preview mr-123 only. Useful when one MR needs a special migration step.

Environment variables¶

All preview environment variables use the PREV_ prefix. They are available in PHP via getenv() and in deploy scripts as shell variables.

Variable	Description
`PREV_IS_PREVIEW`	Always `"true"` in preview environments
`PREV_PROJECT_NAME`	Project slug (e.g. `my-project`)
`PREV_PREVIEW_NAME`	Preview name (e.g. `mr-42`, `branch-develop`)
`PREV_MR_IID`	Merge request IID (empty for branch previews)
`PREV_BRANCH`	Git branch name
`PREV_COMMIT_SHA`	Git commit SHA
`PREV_URL`	Full preview URL (`https://...`)
`PREV_DOMAIN`	Preview domain (without protocol)
`PREV_DB_HOST`	Database hostname
`PREV_DB_NAME`	Database name
`PREV_DB_USER`	Database username
`PREV_DB_PASSWORD`	Database password
`PREV_FILE_PUBLIC_PATH`	Public files path
`PREV_FILE_PRIVATE_PATH`	Private files path
`PREV_FILE_TEMP_PATH`	Temp files path
`PREV_FILE_TRANSLATIONS_PATH`	Translations directory
`PREV_REDIS_HOST`	Redis hostname (if redis/valkey enabled)
`PREV_SOLR_HOST`	Solr hostname (if enabled)
`PREV_SOLR_CORE`	Solr core name (if enabled)
`PREV_DOMAIN_ALIASES`	Comma-separated alias domains
`PREV_LITESPEED_CACHE`	`"1"` if LiteSpeed Cache enabled
`PREV_HTTP_PROXY`	HTTP proxy URL (if proxy configured)
`PREV_HTTPS_PROXY`	HTTPS proxy URL (if proxy configured)

Tip

Custom variables defined under the env: key in druploy.yml are injected as-is (without the PREV_ prefix).

See the full environment variables reference →

Base database & files¶

Each preview starts from a base database dump. Base files (Drupal public files) are optional.

Database (required)¶

Upload a gzipped SQL dump using the CLI:

druploy project push db

The CLI can generate it automatically from your local DDEV environment.

Files (optional)¶

Upload the public files directory. If not provided, an empty files directory is created.

# Exclude image styles (Drupal regenerates them on demand)
druploy project push files --no-image-styles

# Also exclude files larger than 2 MB
druploy project push files --no-image-styles --strip-heavy-files 2mb

Both commands auto-detect the project from the git remote in your current directory. Files are shared across previews using an overlay filesystem — each preview gets its own writable layer on top of the shared base.