Installing and Configuring Statamic in the ServBay Environment

Statamic is a modern content management system (CMS) built on the Laravel framework. It is renowned for its flexibility and robust features, making it an excellent choice for building all types of websites. One of Statamic’s standout features is that it stores content and configuration in the filesystem by default, though it also provides database support as an option.

This article provides a step-by-step guide on how to install and configure Statamic using Composer within ServBay—a powerful local web development environment. ServBay delivers the required PHP environment, built-in Composer support, and convenient site management for Statamic projects.

Steps to Install Statamic

Setting up Statamic in ServBay is straightforward and efficient. Please follow these steps:

Step 1: Create a Project Directory

Begin by creating a subdirectory for your Statamic project within ServBay’s website root directory at /Applications/ServBay/www. Open Terminal and run:

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

This enters ServBay’s default website root, creates a new folder named servbay-statamic-app, and navigates into it.

Step 2: Create a Statamic Project Using Composer

Composer comes pre-installed with ServBay. Composer is a dependency management tool for PHP projects, so you don’t need to install anything extra before creating your Statamic project.

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

composer create-project statamic/statamic .

This will instruct Composer to download the latest version of Statamic along with all its dependencies and install them in the current directory (.). Please wait while the download and installation complete.

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

To serve your Statamic project, you’ll need to add it as a site in the ServBay desktop application.

1. Open ServBay Application: Launch the ServBay desktop app.

2. Navigate to the “Sites” Tab: In the ServBay interface, click the “Sites” tab at the top (Note: In older versions, this may appear as “Hosts”).

3. Add a New Site: Click the plus (+) button in the lower left corner to create a new site configuration.

4. Fill in Site Information:

   • Name: Enter a descriptive name, such as My Statamic Site.
   • Domain: Set your local development domain (the .local suffix is recommended, e.g., servbay-statamic.local). ServBay will auto-configure local DNS resolution.
   • Site Type: Select PHP.
   • PHP Version: Choose the PHP version compatible with your Statamic project (generally, a recent stable version is preferred).
   • Site Root Directory: This is crucial! Statamic’s entry file index.php is located in the project’s public subdirectory, so you must point the site’s root to: /Applications/ServBay/www/servbay-statamic-app/public.

5. Save and Apply: After filling out the required information, click “Save.” ServBay may prompt you to restart services to apply the changes. Follow the prompts to ensure that ServBay’s web server (Caddy or Nginx by default) loads the new site configuration.

Step 4: Configure Statamic Environment

Statamic relies on a .env file in the project root for environment configuration (e.g., app keys, database settings, etc.).

1. Copy the Environment File: In your Statamic project, you’ll find a .env.example template. In Terminal, make sure you’re still in your project root (/Applications/ServBay/www/servbay-statamic-app), then run:

   cp .env.example .env

2. Generate the App Key: Laravel/Statamic requires a unique app key for security purposes, such as session and data encryption. Within the project root, run the artisan command to generate it:

   php artisan key:generate

   This command will automatically generate and fill the APP_KEY value in your .env file.

Step 5: Run and Access Statamic

Your Statamic site should now be configured and running within ServBay.

1. Access Your Statamic Site: Open your web browser and enter the site domain you configured in Step 3 (for example, https://servbay-statamic.local). ServBay automatically generates SSL certificates for your local sites (using ServBay User CA or ServBay Public CA), so you can access via HTTPS. You should see Statamic’s welcome page.
2. Visit the Control Panel: The Statamic admin panel is generally found at the /cp path. Visit https://servbay-statamic.local/cp in your browser, and you will see the login or setup screen for Statamic’s control panel.
3. Create an Admin Account: On your first visit to the control panel, you’ll be guided to create an administrator account. Enter your preferred username, password, and email address, then click “Create Account.” Once completed, you can log in and start managing your Statamic site.

Step 6: Install Plugins and Themes (Optional)

Statamic has a rich ecosystem of plugins and themes to extend its functionality and appearance.

1. Installing Plugins: After logging into the control panel, you can add plugins via the UI (usually found in the left sidebar) or by using Composer commands. The control panel method is typically more intuitive.
2. Installing Themes: Similarly, you can install themes through the control panel or by placing theme files in the specified directories.

Building Your Website with Statamic

With Statamic successfully installed and configured, you can now start building your website using its powerful features. Here are some fundamental tasks to get you started:

Creating Content and Collections

Statamic organizes content using “Collections,” similar to post types or page types in traditional CMSs.

1. Create a Collection: In the Statamic control panel, navigate to “Content” > “Collections” and click “Create Collection.” Name the collection (e.g., Posts, Pages) and define any relevant settings (routes, field blueprints, etc.).
2. Add Content Items: Within your collection, click “New” to add individual content items (such as a blog post or page). Fill in the content using the fields defined in the collection’s blueprint.

Configuring Navigation Menus

You can create and manage site navigation menus.

1. Create Navigation: In the control panel, navigate to “Content” > “Navigation” and click “Create Navigation.” Name your navigation (e.g., Main Navigation).
2. Add Navigation Items: Drag and drop items (from collections or standalone pages) into the navigation structure to organize your site’s menu hierarchy.

Customizing Templates and Styles

Statamic leverages Laravel’s Blade template engine, allowing full control over layout and content rendering.

1. Edit Templates: Views are usually in the resources/views folder in your project root. Edit or create Blade files (.blade.php) following Statamic’s template conventions (using layouts, partials, collections, etc.) to customize your HTML structure. For example, modify resources/views/layouts/default.blade.php to adjust your main page layout.

   <!-- resources/views/layouts/default.blade.php -->
   <!DOCTYPE html>
   <html lang="en">
   <head>
       <meta charset="UTF-8">
       <meta name="viewport" content="width=device-width, initial-scale=1.0">
       <title>{{ $title ?? 'My Statamic Site' }}</title>
       {{-- Reference compiled CSS --}}
       <link rel="stylesheet" href="{{ mix('css/app.css') }}">
   </head>
   <body>
       <header>
           {{-- Example: Render a navigation named 'main_navigation' --}}
           @inject('nav', 'Statamic\View\ViewServiceProvider')
           @if ($main_navigation = $nav->navigation('main_navigation'))
               <nav>
                   <ul>
                       @foreach ($main_navigation->tree() as $item)
                           <li><a href="{{ $item->url() }}">{{ $item->title() }}</a></li>
                       @endforeach
                   </ul>
               </nav>
           @endif
       </header>
       <main>
           {{-- Render the current page’s content --}}
           @yield('content')
       </main>
       {{-- Reference compiled JavaScript --}}
       <script src="{{ mix('js/app.js') }}"></script>
   </body>
   </html>

2. Add Styles and Scripts: Statamic projects typically use Laravel Mix or Vite for frontend asset compilation. Original CSS and JavaScript files are found in resources/css and resources/js.

   For example, add your CSS in resources/css/app.css:

   /* resources/css/app.css */
   body {
       font-family: -apple-system, BlinkMacSystemFont, "Segoe UI", Roboto, Helvetica, Arial, sans-serif, "Apple Color Emoji", "Segoe UI Emoji", "Segoe UI Symbol";
       line-height: 1.6;
       color: #333;
       margin: 0;
       padding: 20px;
   }
   nav ul {
       list-style: none;
       padding: 0;
   }
   nav ul li {
       display: inline;
       margin-right: 15px;
   }

   And add JavaScript in resources/js/app.js:

   // resources/js/app.js
   console.log('Statamic frontend assets loaded!');
   
   // Example: Simple interaction
   document.addEventListener('DOMContentLoaded', function() {
       const navItems = document.querySelectorAll('nav li a');
       navItems.forEach(item => {
           item.addEventListener('mouseover', () => {
               console.log(`Hovering over: ${item.textContent}`);
           });
       });
   });

3. Compile Frontend Assets: To convert these source files into browser-ready CSS and JS, run the frontend build commands. Statamic projects include a package.json file, so use npm or yarn to install dependencies and run compilation. ServBay supports Node.js environments, so you can run:

   npm install
   npm run dev

   npm install installs all frontend dependencies (such as Laravel Mix/Vite, Tailwind CSS, Vue/React, etc.). npm run dev runs a development build, producing unminified assets with source maps for debugging. For production, use npm run prod or npm run build.

Conclusion

By following these steps, you’ve successfully installed, configured, and gotten started using the Statamic CMS within the powerful ServBay local development environment. ServBay’s integrated setup (PHP, Composer, web server, site management, and Node.js support) greatly streamlines local Statamic development. Now you can harness Statamic’s flexible file structure and robust functionality to rapidly build and iterate your website projects.