Getting Started with Drupal: A Beginner's Tutorial

Setting Up Your Environment for Drupal

System Requirements and Tools

Before diving into Drupal 10, ensure your system meets these minimum requirements and recommended tooling for development:

• Web server: Apache or Nginx
• PHP 8.1 or later (Drupal 10 requires PHP 8.1+)
• Database: MySQL 5.7+ / MariaDB 10.3+ / PostgreSQL 12+
• Composer (Composer 2.x) for dependency management
• Drush 11 (recommended for Drupal 10 CLI operations)

Composer is the recommended installation method for production-ready projects because it manages core and contributed module dependencies correctly. Example (run from your development directory):

composer create-project drupal/recommended-project my_site_name

Root domains for official resources: https://www.drupal.org/, https://getcomposer.org/, https://www.php.net/

If Drush is not installed globally on your machine, install it as a development dependency in your project (recommended) or follow the Drush project repository for installation options:

https://github.com/drush-ops/drush

Environment Setup Troubleshooting

Below are common environment problems and concrete fixes you may encounter when preparing a machine for Drupal 10. Each item includes diagnostic commands and actionable remediations.

• PHP version mismatch: Verify the CLI PHP and web server PHP match. In a shell run php -v. For the web server, create a file named phpinfo.php with <?php phpinfo(); ?> inside your web root and open it in a browser to confirm the web-facing PHP version.
• Missing PHP extensions: Drupal requires several PHP extensions. Common ones are gd, curl, mbstring, json, openssl, pdo_mysql or pdo_pgsql, xml, zip, and opcache. On Debian/Ubuntu install them with:

sudo apt update
sudo apt install php8.1-{gd,curl,mbstring,xml,zip,opcache} php8.1-mysql

• File permission errors: The installer may fail if the web server cannot write to sites/default/files or sites/default/settings.php. During development, these are typical safe defaults:

# set ownership to the web server user (example: www-data)
sudo chown -R $USER:www-data web_root_directory
find web_root_directory -type d -exec chmod 755 {} \;
find web_root_directory -type f -exec chmod 644 {} \;
# protect settings.php
chmod 440 web_root_directory/sites/default/settings.php

Replace web_root_directory with your Drupal project's web root (for composer-managed projects this is usually web/ or docroot/ depending on setup).

• SELinux: On Fedora/RHEL/CentOS, SELinux can block writes. Inspect contexts with ls -Z and allow writes with something like:

sudo chcon -R -t httpd_sys_rw_content_t web_root_directory/sites/default/files

• Database connection errors: Confirm DB host, port, name, username, and password. For local installs use 127.0.0.1 instead of localhost to force TCP connections. Ensure the DB user has CREATE, SELECT, INSERT, UPDATE, DELETE, and INDEX privileges on the Drupal database.

Local Development Tools (XAMPP, DDEV, Lando)

XAMPP is a quick way to get Apache, MySQL, and PHP locally. For reproducible development environments that match production closer, consider container-based tooling:

• DDEV — a Docker-based local PHP development environment that supports Drupal 10 and integrates with Composer and Drush. Official site: https://ddev.com/
• Lando — another Docker-driven local dev tool with opinionated presets for Drupal. Official site: https://lando.dev/

Both DDEV and Lando provide reproducible environments and straightforward commands for common tasks (Composer installs, Drush commands, mailcatcher). They are widely adopted for team development because they reduce "works on my machine" issues.

Installing Drupal: Step-by-Step Guide

Downloading and Setting Up Drupal

The recommended method is Composer-based (ensures proper dependency resolution). From a terminal:

composer create-project drupal/recommended-project my_site_name
cd my_site_name
composer require drush/drush --dev

Create a database (example for MySQL). First connect from the shell:

mysql -u root -p

CREATE DATABASE drupal_db CHARACTER SET utf8mb4 COLLATE utf8mb4_general_ci;
CREATE USER 'drupal'@'localhost' IDENTIFIED BY 'secure_password';
GRANT ALL PRIVILEGES ON drupal_db.* TO 'drupal'@'localhost';
FLUSH PRIVILEGES;
EXIT;

Then open your browser at the project web root (for composer-managed projects usually http://localhost:8080 or the host/port provided by your local tooling). Follow the installer prompts and enter the database details.

Security Best Practices

Security decisions during installation and early configuration have long-term impact. Implement these controls immediately:

• Change default admin credentials: Use a unique admin username and a strong password stored in a password manager.
• Protect settings.php: After installation, set permissions to read-only for the web-server user (e.g., chmod 440 sites/default/settings.php). Keep sensitive settings in settings.local.php for development and exclude it from version control.
• Trusted host patterns: Add $settings['trusted_host_patterns'] in settings.php to prevent HTTP Host header attacks.
• Least privilege for DB users: Grant only necessary privileges to the Drupal DB user.
• Use HTTPS: Serve production sites over HTTPS; configure HSTS and secure cookies.
• Update regularly: Keep Drupal core and contributed modules up to date. Use Composer and test upgrades in staging before production.
• Remove or block development tools: Disable web-based installers in production or restrict access by IP and role.

Post-Installation Configuration

Essential Configuration Steps

After installation, perform these steps to make the site production-ready and maintainable:

• Set site name and system email (Configuration > System > Basic site settings).
• Install helpful contributed modules via Composer so they remain tracked in your project. Examples:

composer require drupal/pathauto drupal/admin_toolbar drupal/token

• Enable modules consistently across environments with Drush: vendor/bin/drush en pathauto -y (or drush en pathauto if Drush is global).
• Configure user roles and permissions narrowly; apply least privilege.
• Schedule regular backups for files and database; automate and test restores periodically.

Exploring the Drupal Admin Interface

Navigating the Dashboard

The Drupal admin interface provides quick access to content, structure, people, and configuration. Learn Structure and Extend to manage content types, blocks, and modules effectively.

Useful Drush commands (if using a vendor binary prefix with vendor/bin/):

• Clear cache: vendor/bin/drush cr or drush cr
• Run DB updates after module upgrades: vendor/bin/drush updb
• List available modules: vendor/bin/drush pm:list

Creating Your First Content Type and Content

Defining Content Types

Content types are templates for the content you display. Create them via Structure > Content types > Add content type. Use the Field UI (core) to add fields such as datetime, image, or entity reference.

Example: create an Event content type with a date (datetime), location (plain text), and an image field for flyers. This structure improves reuse and discoverability in Views.

CLI example with Drush (if Drush is installed globally or as a vendor binary):

vendor/bin/drush php-eval "\$node = \Drupal\node\Entity\Node::create(['type' => 'event', 'title' => 'Community Gathering']); \$node->save();"

Enhancing Your Site with Themes and Modules

Understanding Themes

Choose a theme that matches your UX requirements. Bootstrap-based starter themes provide responsive grids; sub-theming preserves upgradeability. To enable a theme via Drush:

vendor/bin/drush theme:enable my_custom_theme

Use Twig for templating and keep preprocessing logic in theme preprocess functions for clearer separation of concerns.

Exploring Modules

Modules extend site functionality. Always install contributed modules via Composer so changes are tracked in your project's composer.json and lock file:

composer require drupal/pathauto drupal/views drupal/webform
vendor/bin/drush en pathauto views webform -y

Monitor module compatibility with Drupal 10 and test updates in a staging environment before deploying to production.

Troubleshooting Common Issues

This section is a practical reference for common issues encountered while developing and maintaining a Drupal site, with commands and next steps.

File permission and ownership problems

If uploads fail or the installer cannot write to sites/default/files:

sudo chown -R www-data:www-data web_root_directory/sites/default/files
sudo find web_root_directory/sites/default/files -type d -exec chmod 755 {} \;
sudo find web_root_directory/sites/default/files -type f -exec chmod 644 {} \;

Adjust www-data to apache or your platform’s web user as appropriate. For containerized setups (DDEV/Lando), use the tooling's recommended file ownership commands.

Missing PHP extensions

If the installer reports missing extensions, the error will usually name the missing extension. Install it and restart services:

# After installing extensions
sudo systemctl restart apache2
# or for nginx + php-fpm
sudo systemctl restart php8.1-fpm
sudo systemctl restart nginx

Composer & dependency errors

If Composer triggers memory or extension errors, try increasing Composer's memory limit temporarily and ensure the CLI PHP matches the web PHP:

COMPOSER_MEMORY_LIMIT=-1 composer update

Database update or module incompatibilities

After an update, run database updates and clear caches:

vendor/bin/drush updb
vendor/bin/drush cr

If a module is incompatible with Drupal 10, either revert to a compatible release (via Composer) or check the module project on https://www.drupal.org/ for updates or migration notes.

Performance or memory issues

If you see out-of-memory errors during Composer or runtime operations, increase PHP memory_limit in php.ini for the environment performing the operation (CLI vs FPM). For production, enable opcache, tune PHP-FPM, and add caching layers (Views caching, Dynamic Page Cache, and a reverse proxy like Varnish) for high-traffic sites.

Next Steps

• Explore advanced theming with Twig and sub-themes to create custom designs.
• Build custom modules for unique application logic and third-party integrations.
• Investigate performance optimization: PHP-FPM tuning, query analysis, and caching layers.
• Join the Drupal community at https://www.drupal.org/ to collaborate and learn from others.