Installing and Configuring Drupal in the ServBay Local Development Environment

Overview

Drupal is a powerful, flexible, and scalable open-source Content Management System (CMS) widely used for building all types of websites—from personal blogs and small business sites to large enterprise portals and complex web applications. It offers rich content management tools, fine-grained user permissions, and a robust modular architecture, making it ideal for developers who need high levels of customization and performance.

ServBay is a local web development environment tool designed specifically for macOS, integrating leading web servers (such as Caddy and Nginx), multiple programming language runtimes (including PHP, Node.js, Python, Go, Java, etc.), databases (like MySQL, PostgreSQL, MongoDB, Redis), as well as developer tools such as Composer and npm. Installing and configuring Drupal in the ServBay environment offers you a stable, convenient, and fully-featured local development platform.

This article provides a detailed guide on how to install and configure Drupal in ServBay, helping you rapidly set up a local Drupal development environment.

Prerequisites

Before installing Drupal, make sure you have the following ready:

1. ServBay Installed and Running: Ensure you have successfully installed ServBay on your macOS and that it is running properly.
2. Basic Knowledge of ServBay Usage: Be familiar with managing packages, adding sites, and accessing built-in tools (like phpMyAdmin) through the ServBay UI.
3. PHP and MySQL/MariaDB Installed: ServBay ships with multiple PHP versions and MySQL or MariaDB databases. Ensure your desired PHP version is enabled and the database service is running.
4. Composer Installed: ServBay includes Composer by default, a key tool for managing modern PHP project dependencies. This guide will use Composer to create the Drupal project.

Steps to Install Drupal

Follow these steps to install and configure Drupal in ServBay:

Step 1: Create the Project Directory

First, create a dedicated subdirectory for your Drupal project under ServBay’s web root at /Applications/ServBay/www.

Open Terminal and run:

cd /Applications/ServBay/www
mkdir servbay-drupal-app
cd servbay-drupal-app

This creates a new folder called servbay-drupal-app under /Applications/ServBay/www and navigates into it.

Step 2: Create a Drupal Project Using Composer

Composer is pre-installed in ServBay, so no additional setup is required. The official recommendation is to use Composer to create and manage Drupal projects.

Within the servbay-drupal-app directory you just created, run:

composer create-project drupal/recommended-project .

This command uses the drupal/recommended-project template to create a new Drupal project in the current directory (.). Composer will automatically download the Drupal core files and required dependencies. The process may take a few minutes depending on your internet speed.

The drupal/recommended-project template places all publicly accessible files (such as index.php, CSS, JavaScript files, etc.) in a web subdirectory. This structure is standard for modern Drupal projects and enhances security.

Step 3: Create the Database and User

Drupal needs a database to store its content, configuration, and user data. You can use ServBay’s integrated phpMyAdmin tool to create a database and user.

1. Access phpMyAdmin via ServBay

   Open your web browser and visit ServBay’s default dashboard: https://servbay.host/. On the dashboard, find and click the "phpMyAdmin" link (usually under “Tools” or “Databases”) to enter the phpMyAdmin interface.

   servbay.host is a special domain set up by ServBay for local development, pointing to its management interface.

2. Create a Database User

   For better security and access control, create a dedicated database user for your Drupal project.

   • Go to the User Accounts Page: On the phpMyAdmin homepage, click the “User Accounts” tab in the top navigation menu.
   • Add a New User: Click “Add user account”.
   • Fill in User Details:
     • Username: Enter a desired username, such as drupal_user.
     • Host: Choose or enter localhost, which ensures the user can only connect from the local machine, enhancing security.
     • Password: Enter a secure password. Do not use weak passwords; the example password123 is for demonstration purposes only. In real projects, generate a strong, complex password.
     • Re-type: Re-enter your chosen password.
   • Database Privileges: In the "Database for user account" section, check the box for "Create database with same name and grant all privileges". This will automatically create a database named drupal_user and grant all privileges to the new user on this database.
   • Global Privileges: Make sure “Grant all privileges on all databases” is not selected (unless you know exactly what you're doing). We only need user-level privileges on their own database.
   • Go: Review your info, then click the “Go” button at the bottom right.

   You have now created a database named drupal_user and a user called drupal_user, with all necessary permissions on that database.

Step 4: Configure the Web Server (Add a Site in ServBay)

Next, configure a site in ServBay, pointing a local domain to your Drupal project’s web directory.

1. Open the ServBay UI: Launch the ServBay application interface.
2. Add a New Site: Click on the “Sites” tab in the left sidebar.
3. Click the Add Button: On the site list page, click the “+” (add) button at the bottom to create a new site configuration.
4. Fill in Site Info:
   • Name: Enter an easily recognizable name, such as My Drupal Site.
   • Domain: Enter your preferred local domain for Drupal, e.g., servbay-drupal.local. ServBay supports .local domains for local development without editing your system hosts file.
   • Site Type: Choose PHP.
   • PHP Version: Select the PHP version you want for this Drupal site from the dropdown. Check Drupal’s official documentation for PHP version compatibility.
   • Site Root Directory: This step is crucial. Set the root directory to the subdirectory containing Drupal’s entry file (index.php). For projects created using Composer in Step 2, the entry file is in the web directory. So the site root should be: /Applications/ServBay/www/servbay-drupal-app/web.
5. Save Configuration: Once all details are entered, click “Save” (or the corresponding button) in the ServBay UI. ServBay will automatically update the web server configuration and apply the changes.

Step 5: Run the Drupal Installer

Now you can launch Drupal’s web installer by visiting your configured local domain.

1. Access the Installer

   Open your browser and go to the domain you set in Step 4, appending /core/install.php: https://servbay-drupal.local/core/install.php.

   You should see Drupal’s installation wizard.

2. Select Language

   Choose your site’s default language and click “Save and Continue”.

3. Choose Installation Profile

   Select the installation type you prefer. Typically, "Standard" is recommended for a default feature set. Click “Save and Continue”.

4. Enter Database Information

   The installer will prompt you for database connection details. Enter the information from Step 3:

   • Database Type: Select MySQL, MariaDB, Percona Server, or equivalent.
   • Database Name: Enter drupal_user (matching your created database).
   • Database Username: Enter drupal_user.
   • Database Password: Enter the password set for drupal_user in Step 3.
   • Database Host: Enter localhost.
   • Advanced Options: Typically not required unless your database runs on a non-default port or has special settings.

   After filling in, click “Save and Continue”. Drupal will attempt to connect and import the initial data.

5. Fill in Site Information

   If the database connection succeeds, you’ll be asked for basic site info:

   • Site Name: The title of your website.
   • Site Email Address: The address for notifications and correspondence.
   • Administrator Username: The username for logging in to the Drupal dashboard.
   • Administrator Password: A secure password for the admin account.
   • Country/Region: Select your country/region.
   • Time Zone: Select the time zone for your site.

   After entering these, click “Save and Continue”. Drupal will complete the final installation steps, generating configuration files, setting up the site, etc.

6. Finish Installation

   Once finished, you’ll be redirected to your new Drupal site’s home page. Congratulations—Drupal is successfully installed in ServBay!

Step 6: Installing Modules & Themes (Getting Started)

Drupal stands out for its ecosystem of modules and themes. After installation, you can customize your site as needed.

1. Log into Drupal Admin: Go to https://servbay-drupal.local/user or https://servbay-drupal.local/admin and sign in using the admin credentials set in Step 5.
2. Install Modules: Once logged in, navigate to “Extend” in the admin menu. Here you can browse, search, and install new modules to add features to your site.
3. Install Themes: Go to “Appearance” to install and manage themes for changing your site’s look and feel.

Post-Installation Configuration and Usage

With Drupal successfully installed, you can now leverage its features to build your website. Here are some common first steps:

Creating Content Types and Content

Content types define the structure of various content (e.g., articles, pages).

1. Create Content Types: In the Drupal admin, go to “Structure” → “Content types”. Edit existing types or click “Add content type” to create a new one, defining its fields (title, body, image, etc.).
2. Create Content: Navigate to “Content” → “Add content”, choose the type you want, fill out the fields, and click “Save and publish”.

Configuring Navigation Menus

Menus organize your site’s navigation links.

1. Create Menus: In the Drupal admin, go to “Structure” → “Menus”. Add a new menu or edit an existing one.
2. Add Menu Items: Edit a menu, click “Add link”, enter the link text and target path (internal, like /node/1, or external URL), then save.

Customizing Block Layout

Blocks are customizable content units that can be placed in site regions (such as sidebars or footers).

1. Add Blocks: In the Drupal admin, go to “Structure” → “Block layout”. This page shows regions available in the current theme. Drag blocks (such as navigation or custom blocks) into desired regions.
2. Configure Blocks: Click “Configure” next to a block to set the title, visibility by page/user role, and other options.

Notes and Frequently Asked Questions (FAQ)

• How can I change PHP settings? If Drupal requires specific PHP extensions or higher memory limits (memory_limit), go to the “Packages” tab in the ServBay UI, find your PHP version, and click the configure button to edit php.ini. After changes, restart the PHP service (ServBay will usually prompt or handle this automatically).
• Why can't I access my website?
  • Check that ServBay is running.
  • Double-check your ServBay site configuration, especially the domain and site root directory. Make sure the root points to .../servbay-drupal-app/web.
  • Ensure the ServBay web server (Caddy or Nginx) is running.
  • Access the correct URL: https://servbay-drupal.local (initial install at https://servbay-drupal.local/core/install.php).
• What if database connection fails?
  • Make sure the database name, user, and password match what you created in phpMyAdmin.
  • The database host should be localhost.
  • Ensure MySQL/MariaDB is running in ServBay.
• Composer dependency installation errors? Check your network; Composer must reach packagist.org. Sometimes, clearing the Composer cache or updating Composer (ServBay updates its built-in version regularly) can help.
• File permission problems? Drupal needs write access to some directories (e.g., web/sites/default/files and web/sites/default/settings.php). ServBay typically runs under your user account, minimizing permission issues on macOS, but if you encounter them, check and adjust permissions as needed.

Summary

By following this guide, you have successfully installed and configured Drupal in the ServBay local development environment. ServBay provides a convenient and efficient platform with all needed components integrated for Drupal development. Now you can leverage Drupal’s powerful features to build your site, and perform local development, testing, and debugging within ServBay. As your project grows, ServBay’s flexibility makes it easy to manage different PHP versions, databases, and other services to meet your needs.