Installing and Configuring Craft CMS in the ServBay Environment

Overview

Craft CMS is a powerful content management system (CMS) highly regarded by developers for its flexible content modeling, intuitive user interface, and developer-friendly features. It's an excellent choice for building complex and customized websites.

Using ServBay as a local development environment for Craft CMS offers numerous advantages, including pre-configured PHP, databases (such as MySQL or PostgreSQL), web servers (Caddy or Nginx), and built-in Composer and command-line tools, all of which greatly simplify the installation and configuration process.

This guide will walk you through the steps to install and configure a Craft CMS project within ServBay.

Prerequisites

Before you begin, make sure you have the following in place:

1. ServBay is installed and running: Ensure you have successfully installed ServBay on your macOS system, and that the required PHP version (Craft CMS has version requirements; see the Craft CMS official documentation) and database (usually MySQL or PostgreSQL) are started. ServBay supports multiple PHP versions and databases, allowing you to easily switch and configure as needed for Craft CMS.
2. Basic command line proficiency: You'll need to use the Terminal to run certain commands, such as creating directories and running Composer.
3. Familiarity with Composer: Craft CMS uses Composer to manage dependencies. ServBay has Composer built in, but you should know how to run the composer create-project command.

Steps to Install Craft CMS

Follow these detailed steps to install and configure Craft CMS in the ServBay environment.

Step 1: Create the Project Directory

First, create a new project directory within ServBay’s default web root directory at /Applications/ServBay/www. By default, ServBay configures this directory as the web server’s root, allowing you to access your projects directly.

Open Terminal and run:

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

This will create a new folder named servbay-craft-app under /Applications/ServBay/www and switch into that directory.

Step 2: Use Composer to Create the Craft CMS Project

Since Composer is bundled with ServBay, you can use it directly in the project directory to create your Craft CMS project. The Craft CMS team recommends Composer as the preferred installation method.

In the servbay-craft-app directory, run:

composer create-project craftcms/craft .

This command downloads the latest version of Craft CMS and its dependencies into the current directory (.). Wait for Composer to finish the download and installation process.

Step 3: Create Database and User

Craft CMS requires a database to store content and configuration information. We’ll use ServBay’s built-in phpMyAdmin or Adminer tool to create your database and user. We’ll use phpMyAdmin as an example here.

1. Access ServBay's database management tool (phpMyAdmin)

   Open your browser and navigate to ServBay’s local development panel at https://servbay.host/. Find and click on the “phpMyAdmin” link to enter the database management tool.

   Tip: The default user for ServBay’s phpMyAdmin is usually root, with password ServBay.dev. For security, it’s recommended to change your root password or create a new admin user as soon as you connect.

2. Create a database user

   Although you can connect Craft CMS as root, for better security and easier permission management, it’s best practice to create a separate database user for each application.

   1. Go to the user accounts page

      In phpMyAdmin’s main interface, click “User accounts” in the top menu.

   2. Add a new user

      Click “Add user account”. Fill in the following details:

      • Username: Enter a username for the Craft CMS database connection, e.g., craft_user.
      • Host: Select localhost (indicating the user can only connect from the local machine).
      • Password: Enter a secure password. Do not use the sample password123, especially in production. For local development, a simpler password is acceptable for testing, but always keep security in mind.
      • Re-type: Enter the password again to confirm.
      • In the “Database for user” section, choose the option to "Create database with same name and grant all privileges". This will automatically create a database named craft_user and grant full privileges to this user.
      • Make sure “Grant all privileges” is checked.
      • Click “Go” at the bottom of the page.

   You now have a database user craft_user, a database with the same name, and the correct privileges assigned.

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

To serve your Craft CMS project with ServBay’s web server (Caddy or Nginx), you’ll need to add a “site” configuration within ServBay.

1. Open the ServBay application

   Launch ServBay.

2. Add a new site

   Click the “Sites” tab in the left sidebar (in some older versions, this may appear as “Hosts”). Then click the “+” button or the “Add Site” button on the right to create a new site configuration.

   Fill in the following information:

   • Name: Give your site a recognizable name, e.g., My Craft Site.
   • Domains: Enter the domain you wish to use to access the site locally, e.g., servbay-craft.local. ServBay will automatically handle local DNS so you can visit the site using this domain.
   • Type: Choose PHP.
   • PHP Version: Select the PHP version confirmed in your prerequisites that is compatible with Craft CMS. ServBay allows you to install and run multiple PHP versions simultaneously.
   • Website Root: This is especially important. Craft CMS’s public files (such as index.php) are located inside the web subdirectory of your project. For security, the web server root should point directly to this web directory, not to the overall project root. Use the following path: /Applications/ServBay/www/servbay-craft-app/web Double-check the path to make sure it points specifically to the web folder inside the created project directory.

3. Save the configuration

   After filling in all details, click “Save”. ServBay will reload the web server configuration so your new site is active. In the ServBay site list, you should now see your new servbay-craft.local site.

Step 5: Run the Craft CMS Installer

You’re now ready to run the Craft CMS web-based installer by accessing your configured domain in the browser.

1. Visit the installer page

   Open your browser and go to https://servbay-craft.local/. Craft CMS will detect that it’s not yet installed and automatically redirect to the install page, usually https://servbay-craft.local/index.php?p=admin/install.

2. Enter database connection details

   On the database configuration step of the installer, enter the details from step 3:

   • Database Server: localhost
   • Database Name: craft_user (or the database name you created)
   • Username: craft_user (or the user you created)
   • Password: The password for the craft_user user you set earlier.

   Click to continue. Craft CMS will attempt to connect to the database. If successful, you’ll move to the next step.

3. Set up the admin account

   Follow the prompts to create your Craft CMS admin account. Enter your desired username, password, and email address. Choose a secure password.

   Click continue.

4. Site setup

   Fill in your site’s name and other basic information.

   Click the “Finish Up” button. Craft CMS will finalize the installation, including creating database tables and generating configuration files.

   When finished, you’ll be redirected to the Craft CMS admin login page.

Step 6: Initial Configuration and Exploration

After logging in to the Craft CMS admin panel, you can perform some initial configurations and explore:

1. Check the .env file: Craft CMS uses a .env file for environment variables, including database connection info. The installer generates this file automatically; you’ll find it in your project’s root directory (servbay-craft-app/). You can edit this file, for example, to set CRAFT_ENVIRONMENT=dev.
2. Install plugins: In the admin panel, click “Plugins” to browse, install, and manage Craft CMS plugins for added features.
3. Create content structure: Explore the “Settings” section to define your fields, sections, categories, tags, and other content structures.
4. Configure mail sending: If you need to test email sending locally, configure Craft CMS to use ServBay’s built-in Mailpit or Mailhog. In the .env file or through the admin mail settings, set the mailer to SMTP, with the server as localhost and the port to Mailpit/Mailhog’s SMTP port (as shown in the ServBay panel).

Frequently Asked Questions (FAQ)

• Q: What should I do if I get a database connection error during installation?
  • A: Double-check that the database server (localhost), database name, username, and password entered in the Craft CMS installer match exactly what you created in phpMyAdmin. Make sure ServBay’s database service (MySQL or PostgreSQL) is running.
• Q: Visiting servbay-craft.local results in a 404 error or blank page?
  • A:
    • Ensure the “Website Root” you set in ServBay is exactly /Applications/ServBay/www/servbay-craft-app/web. This is a common mistake.
    • Make sure the ServBay web server (Caddy or Nginx) and the corresponding PHP service are running.
    • Check if the servbay-craft.local site configuration is enabled in ServBay’s site list.
• Q: Composer is slow or fails to install Craft CMS?
  • A: This is likely a network issue or related to the Composer mirror. You can try switching Composer’s repository mirror to one closer to your region (e.g., Alibaba Cloud or Packagist China).
• Q: After installation, why are the admin panel or frontend styles missing or images not displaying?
  • A: This is usually a file permissions problem. Make sure the user running ServBay has write permissions for directories like storage and web/cpresources. ServBay typically manages permissions automatically, but if you have issues, manually check or reset the permissions for these directories.

Conclusion

By following the steps above, you should have successfully installed and configured Craft CMS in your ServBay local development environment. ServBay’s integrated setup streamlines PHP version management, database setup, and web server configuration, allowing you to focus on developing your Craft CMS application. Now you're ready to harness Craft CMS's powerful content modeling features to build your website or application!