Installing and Configuring OctoberCMS in the ServBay Environment

Overview

OctoberCMS is an open-source content management system (CMS) built on the robust Laravel framework, known for its simplicity, flexibility, and developer-friendly features. This documentation will guide you step-by-step through installing and configuring OctoberCMS in ServBay—a one-stop local web development environment designed for macOS—so you can quickly kick off your OctoberCMS-based project development.

What is OctoberCMS?

OctoberCMS features an intuitive back-end interface along with powerful front-end development capabilities, letting developers build all kinds of websites—from simple blogs to complex enterprise apps—by leveraging familiar Laravel concepts like Eloquent ORM and the Blade template engine.

Prerequisites

Before installing OctoberCMS, make sure you meet these requirements:

1. ServBay is installed and running on your macOS system.
2. The PHP package (version 7.4 or higher recommended) and MySQL/MariaDB packages are enabled and running in ServBay.
3. The Composer package is enabled in ServBay.
4. You are familiar with basic command line operations.

Steps to Install OctoberCMS

Follow these steps to install and configure OctoberCMS within the ServBay environment:

Step 1: Create a Project Directory

First, navigate to ServBay's recommended web root at /Applications/ServBay/www, and create a new directory for your OctoberCMS project.

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

Step 2: Install OctoberCMS Using Composer

ServBay comes bundled with Composer, already configured. Make sure the Composer package is enabled in the ServBay control panel. While inside your new project directory, run the Composer command to download and install OctoberCMS core files:

composer create-project october/october .

This command will fetch the latest version of OctoberCMS from the official repository into the current directory (.).

Step 3: Create the Database and User

OctoberCMS requires a database to store content, users, and configuration. We'll use ServBay's built-in phpMyAdmin tool to create a database and corresponding user.

1. Access phpMyAdmin provided by ServBay

   Open your browser and visit ServBay's local development panel at https://servbay.host/. Click or navigate to the phpMyAdmin link, typically https://servbay.host/phpmyadmin/, to access the database management interface.

2. Create a Database User

   For security and data isolation, it is recommended to create a separate database and user for each application.

   1. Go to the User Accounts Page

      On the phpMyAdmin main page, click "User accounts" in the top menu.

   2. Add a New User

      Click "Add user account" and fill in the following details:

      • Username: Enter a username for OctoberCMS to access the database, e.g., october_user.
      • Host: Choose localhost or 127.0.0.1 to limit access to local connections for added security.
      • Password: Set a strong, unique password. Do not use example passwords like password123 in production.
      • Re-type: Enter the password again for confirmation.
      • In the "Database for user" section, select "Create database with same name and grant all privileges." This will automatically create a database named october_user and assign all permissions to the october_user account.
      • Ensure that the "Grant all privileges on database" option is checked under "Global privileges" (usually auto-selected if you chose to create and grant privileges in the previous step).
      • Scroll down and click the "Go" button to complete database and user creation.

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

To access your OctoberCMS application via browser, you'll need to set up a local website in ServBay.

1. Add a New Site

   Open the ServBay control panel and click the "Sites" tab in the left sidebar (note: in older versions, it may be called "Hosts"). Click the "Add Site" button.

   Fill in these details:

   • Name: Give your site an easily identifiable name, e.g., My OctoberCMS Site.
   • Domain: Enter your preferred local domain, e.g., servbay-octobercms.local. Use the .local suffix to avoid conflicts with real domains.
   • Site Type: Select PHP.
   • PHP Version: Choose the PHP version for this site, making sure it matches the version enabled in ServBay and meets OctoberCMS requirements.
   • Web Root: Click the browse button and select the project directory you created in Step 1: /Applications/ServBay/www/servbay-octobercms-app.

2. Save and Restart ServBay

   After filling in the details, click Save. ServBay will prompt you to apply changes, which usually requires restarting relevant services (e.g., Caddy or Nginx) and possibly ServBay itself. Follow any prompts to ensure changes take effect. ServBay will automatically resolve servbay-octobercms.local to your local machine (127.0.0.1).

Step 5: Configure OctoberCMS Environment Variables

OctoberCMS (built on Laravel) uses the .env file to manage application environment variables, including database credentials and app keys.

1. Copy the Example Environment File

   In your OctoberCMS project root (/Applications/ServBay/www/servbay-octobercms-app), copy .env.example and rename it to .env:

   cd /Applications/ServBay/www/servbay-octobercms-app
   cp .env.example .env

2. Edit the .env File

   Open the new .env file in your favorite text editor. Locate the database configuration section and update the values according to the database and user you created in Step 3:

   # ... other settings ...
   
   DB_CONNECTION=mysql
   DB_HOST=127.0.0.1
   DB_PORT=3306
   DB_DATABASE=october_user  # Replace with your actual database name
   DB_USERNAME=october_user  # Replace with your actual database username
   DB_PASSWORD=password123   # Replace with your actual password
   
   # ... other settings ...

   Important: Make sure to replace DB_DATABASE, DB_USERNAME, and DB_PASSWORD with the actual values you set up in Step 3.

Step 6: Run the OctoberCMS Installer

OctoberCMS offers a web-based installation wizard to finalize setup, including database migration and creation of the admin account.

1. Visit the Installer Page

   Open your browser and visit the local domain you configured in Step 4, appending /install.php. For example:

   https://servbay-octobercms.local/install.php

   You should see the OctoberCMS installation wizard.

2. Enter Database Information

   The installer will prompt you for database credentials. Use the same information you entered in the .env file:

   • Database Type: MySQL
   • Database Host: localhost or 127.0.0.1
   • Database Name: october_user
   • Database Username: october_user
   • Database Password: password123

   (Again, make sure to use your actual password)

3. Admin Account Setup

   Continue through the prompts and set up your OctoberCMS admin account (username, password, email, etc.).

4. Complete Installation

   Click the "Install" (or equivalent) button in the wizard. The installer will handle database migrations, generate the application key, and set up your new CMS. Wait for the process to finish.

Step 7: Install Plugins and Themes (Optional)

Once installation is complete, you can log in to the OctoberCMS back-end (https://servbay-octobercms.local/backend).

1. Install Plugins

   In the admin panel, navigate to "System" -> "Updates" -> "Plugins." Search and install a variety of plugins from the OctoberCMS Marketplace to extend your site's functionality.

2. Install Themes

   Navigate to "System" -> "Updates" -> "Themes" to browse and install themes that best fit your project's needs.

Basic Post-Installation Configuration and Usage

Now that OctoberCMS is installed, you can start building your site. Here are some common initial tasks:

• View the Frontend: Go to your local domain at https://servbay-octobercms.local/ to view the site’s frontend (typically the default theme).
• Log in to the Backend: Visit https://servbay-octobercms.local/backend and use the admin credentials you set up during installation.
• Create Pages: In the backend, go to "CMS" -> "Pages" to create and edit website pages.
• Create Content Blocks: In the backend, go to "CMS" -> "Content" to build reusable content snippets.
• Configure Themes: Under "CMS" -> "Themes" you can change and customize your current theme, layouts, and partials.
• Manage Users and Permissions: Under "System" -> "Manage," you can oversee backend users and their permissions.

Frequently Asked Questions (FAQ)

• Q: Visiting servbay-octobercms.local displays the ServBay default page or an error?

  • A: Please verify in the ServBay control panel that the servbay-octobercms.local site has been added successfully and that the web root is correctly set to /Applications/ServBay/www/servbay-octobercms-app. Make sure you’ve applied changes and that ServBay has fully restarted the necessary services. Ensure Caddy/Nginx and PHP packages are running.

• Q: Visiting https://servbay-octobercms.local/install.php displays a blank page or errors?

  • A: This is typically due to PHP errors. Check the PHP error logs in the ServBay control panel for more details. Common causes include file permission issues (ensure storage, themes, and plugins directories and their subfolders are writable by the web server user), incompatible PHP versions, or missing PHP extensions.

• Q: Database connection errors during installation?

  • A: Double-check your .env database configuration (DB_HOST, DB_PORT, DB_DATABASE, DB_USERNAME, DB_PASSWORD) and ensure they match exactly with what you set up in phpMyAdmin. Also, ensure that the MySQL/MariaDB service is running in ServBay.

• Q: The composer create-project command fails?

  • A: Make sure the Composer package and the correct PHP version are enabled in ServBay. Also, check your internet connection; Composer needs to download files from the internet.

Summary

Thanks to ServBay’s quick and convenient environment, you can easily install and configure OctoberCMS on macOS. By following this guide, you'll be able to set up a powerful, developer-friendly local development platform for your next web project. Now it’s time to explore OctoberCMS's rich features and build an amazing website!