🚀 Drupal Project Template

A clean, production-ready boilerplate for launching professional Drupal projects with Docker-based local development and secure environment configuration.

✨ Features

• Drupal Ready: Pre-configured out of the box for the latest core standards, modern PHP, and MariaDB.
• Automated Dotenv Setup: The local /.env file is automatically generated from .env.example during the first Composer installation (safely prevents accidental overwrites).
• Flexible DB Mapping: Uses generic, industry-standard DB_ environment variables instead of hardcoded credentials.
• Clean Git Workflow: Fine-tuned .gitignore ensures a seamless cross-platform experience (Linux, macOS, Windows).

📋 Prerequisites

Make sure you have the following installed on your system:

• Docker & DDEV
• Git

---

🛠️ Guide for a Newly Created/Cloned Project

When you create a new, independent project using this template (e.g., via GitHub's "Use this template" button or by cloning it), follow these steps inside your new project directory to initialize your environment:

1. Create your project & reset Git

Click the "Use this template" button on GitHub, or clone this repository into your new project directory.

If you cloned it manually via CLI, you must disconnect it from the template repository and start a fresh Git history for your independent project:

# Clone the template
git clone https://github.com/bebehr/drupal-project my-new-project
cd my-new-project

# Purge the template's Git history
# For macOS / Linux:
rm -rf .git
# For Windows (PowerShell):
Remove-Item -Recurse -Force .git

# Initialize a brand new repository
git init
git add .
git commit -m "Initial commit from Drupal project template"

2. Start the DDEV environment

Initialize and spin up the local Docker containers. Since the name parameter is omitted from config.yaml, DDEV will automatically detect your new folder name and configure the local domain accordingly (e.g., https://my-new-project.ddev.site):

ddev start

3. Install dependencies & generate .env

Run the Composer installation inside the running DDEV container. This command downloads all required Drupal core and contrib packages. It also triggers the automated script to safely create your local /.env file:

ddev composer install

4. Perform the Site Installation

Install Drupal using Drush. Local database configurations and credentials are automatically injected into Drupal via DDEV's internal settings.ddev.php, meaning no manual setup is required:

ddev drush si -y

5. Log in to your new instance

Generate a secure, one-time login link to access the Drupal admin dashboard:

ddev drush uli

(Optional: Run ddev launch to automatically open the project in your default browser).

---

💡 Development & Best Practices

• Custom Code: Place your custom modules in web/modules/custom/ and your custom themes in web/themes/custom/.
• Contrib Modules: Always install community modules via Composer inside the DDEV container: ddev composer require drupal/module_name. They will be automatically sorted into the contrib directories.
• Debugging with Xdebug: Toggle Xdebug instantly on or off using ddev xdebug on and ddev xdebug off.
• Production Deployment: This template uses generic DB_* environment variables for production environments. When deploying to a live server, simply populate the real credentials in your server's environment or the production /.env file. The settings.php will automatically pick them up if DDEV is not running.