Installing and Configuring Sculpin in the ServBay Environment

Overview

Sculpin is a powerful and flexible PHP-based static site generator, perfect for building blogs, documentation sites, or any project that needs to transform dynamic content (such as Twig templates and Markdown files) into high-performance static HTML pages. It uses Composer for dependency management and is built upon Symfony components, offering developers a familiar and reliable development experience.

ServBay is a local web development environment designed specifically for macOS. It integrates a wide range of common packages, including PHP, Composer, databases (MySQL, PostgreSQL, MongoDB, Redis), and web servers (Caddy, Nginx). ServBay also provides a convenient graphical management interface. Using ServBay greatly simplifies setting up a Sculpin development environment on macOS—especially when handling PHP version selection, dependency management, and web server configuration.

This guide provides step-by-step instructions on how to install and configure Sculpin within the ServBay environment and set up a local development site.

Use Cases

• Build high-performance static blogs with a PHP tech stack.
• Generate static documentation sites for open-source projects or products.
• Quickly set up static marketing pages or business websites that don't require a backend database.
• Take advantage of the Twig templating engine and Markdown for content creation, benefiting from static site performance and security.

Prerequisites

Before you begin, make sure you have the following:

1. ServBay installed and running on macOS. ServBay provides the required PHP environment, Composer dependency manager, and web server (Caddy or Nginx).
2. Basic knowledge of working with the command line.
3. Familiarity with PHP, Composer, and Markdown concepts.

Steps to Install Sculpin

Below are the detailed steps to install and configure Sculpin in the ServBay environment:

Step 1: Create a Project Directory

First, create a new project directory under ServBay's website root (/Applications/ServBay/www). We’ll use servbay-sculpin-app as the example project name.

Open your Terminal and run:

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

This directory will hold your Sculpin project files.

Step 2: Create a Sculpin Project Using Composer

ServBay comes with Composer pre-installed—no need for additional installation. You can use the composer command directly in the terminal.

We'll use the official Sculpin blog skeleton to quickly bootstrap the project. In the newly created servbay-sculpin-app directory, run the following Composer command:

composer create-project sculpin/sculpin-blog-skeleton .

This command tells Composer to download the Sculpin blog skeleton and all its dependencies, installing them into the current directory (.).

Step 3: Configure the ServBay Website

To access your Sculpin website via ServBay’s web server (Caddy or Nginx), add a new website configuration in ServBay.

1. Open the ServBay App: Launch the ServBay graphical interface.
2. Go to the "Websites" Tab: In the ServBay window, click on the "Websites" tab in the navigation bar.
3. Add a New Website: Click the "+" button in the bottom left to add a new website configuration.
4. Fill in Website Details:
   • Name: Enter an easily identifiable name, such as My Sculpin Site.
   • Domain: Enter the local domain you want to use for access, such as servbay-sculpin.local. ServBay will automatically configure local DNS and SSL certificates for .local domains using its User CA.
   • Type: Select PHP since Sculpin is a PHP application.
   • PHP Version: Choose the PHP version you want to use. ServBay supports multiple PHP versions; select one compatible with Sculpin (any recent version usually works).
   • Document Root: This step is crucial. Sculpin generates static files into output_dev or output_prod directories under the project. For local development, point your document root to the development output directory: /Applications/ServBay/www/servbay-sculpin-app/output_dev
5. Save Configuration: After filling out the details, click the "Save" button. ServBay will automatically apply the new site configuration to its web server (Caddy or Nginx); you usually don’t need to restart the ServBay service manually.

Step 4: Build the Sculpin Site

Once you’ve configured your website in ServBay, you need Sculpin to generate the site’s static files.

In the Terminal, make sure you’re still in the project root /Applications/ServBay/www/servbay-sculpin-app, then run the following command to install dependencies (if you already ran Step 2, this step can be skipped, but it's okay to run again to ensure everything’s installed):

composer install

Next, generate the site with Sculpin and enable file watching:

vendor/bin/sculpin generate --watch

• vendor/bin/sculpin: The path to the Sculpin executable installed via Composer.
• generate: Sculpin's command to generate the static site. It reads the contents and templates from the source directory, then outputs static files to the configured output directory (default is output_dev).
• --watch: Tells Sculpin to watch the source directory for changes. Whenever you edit files there, Sculpin will automatically regenerate the site—a huge help during development.

Once the command runs and displays "Sculpin has generated your site!" or similar, the static files are in the output_dev directory.

Step 5: Access Your Local Development Site

Now you can access your Sculpin site via the domain you set up in ServBay.

Open your web browser and go to the domain you configured in Step 3:

https://servbay-sculpin.local

Since you set the site's document root to output_dev and have sculpin generate --watch running to monitor file changes, you can now preview your site live at https://servbay-sculpin.local as you edit content and templates. ServBay’s automatic SSL certificate ensures you can securely access your local site via HTTPS.

Developing with Sculpin

Now that you’ve successfully set up Sculpin in ServBay, you can start building your static site. Here are some basic development operations:

Project Structure Overview

Understanding Sculpin’s project structure helps you develop efficiently:

servbay-sculpin-app/
├── app/                # App configs and cache
├── output_dev/         # Development output directory for generated static files (ServBay document root points here)
├── output_prod/        # Production output directory for static files
├── source/             # Website source files (Markdown content, Twig templates, static assets, etc.)
│   ├── _layouts/       # Twig layout files
│   ├── _posts/         # Blog posts in Markdown
│   ├── assets/         # Static assets (CSS, JS, images, etc.)
│   └── index.md        # Homepage Markdown file
├── vendor/             # Composer dependencies
├── sculpin.yml         # Main Sculpin config file
├── composer.json       # Composer dependency configuration
└── ...other files

You’ll mainly work in the source directory.

Creating a Blog Post

To add a new post to your Sculpin blog, simply create a new Markdown file under source/_posts. File names typically follow the YYYY-MM-DD-slug.md format.

For example, create a file 2024-06-06-my-first-post.md:

---
title: "My First Post"
date: 2024-06-06
tags: [Tutorial, Sculpin, ServBay]
---

# My First Post

This is the content of my first Sculpin blog post. Here, I'm sharing some experiences using ServBay and Sculpin.

You can use Markdown syntax here to write your content.

## Subheading

List:
- Item 1
- Item 2

After saving the file, since you have sculpin generate --watch running, Sculpin will automatically detect the change and regenerate the site. Simply refresh https://servbay-sculpin.local in your browser to see your new post.

Creating a New Page

To add a standalone page (e.g., an "About Us" page), simply create a Markdown file in the source directory, e.g., about.md:

---
title: "About Us"
layout: page.html.twig # Specify the layout file to use
---

# ServBay Sculpin Guide

This page is a guide on building static sites using ServBay and Sculpin.

After saving, Sculpin will generate output_dev/about/index.html (if pretty URLs are configured). You can access this page at https://servbay-sculpin.local/about/.

Customizing Styles and Scripts

Static assets (like CSS and JavaScript files) are typically stored in the source/assets directory. You can edit these files directly.

For example, edit source/assets/css/style.css to modify your site's appearance.

These resources are copied to the output directory during site generation. If you change them, Sculpin’s --watch will pick up the changes and trigger a rebuild.

Building the Production Version of the Site

When your site is ready to go live, you’ll want to build a production-ready version, typically with optimizations like asset minification.

Build the site for production with:

vendor/bin/sculpin generate --env=prod

This outputs static files to the output_prod directory. You can upload all files from output_prod to any static hosting service (like GitHub Pages, Netlify, Vercel, or your own web server) for deployment.

If you want to preview the production build in ServBay, simply update the site's "Document Root" to /Applications/ServBay/www/servbay-sculpin-app/output_prod in ServBay, then save and visit your site’s domain.

Tips & Notes

• Make sure ServBay is running and your site configuration is enabled.
• Ensure the sculpin generate --watch command is running in your Terminal for automatic site updates during development.
• Check that your ServBay site’s "Document Root" points to the correct Sculpin output directory (typically output_dev when developing).
• ServBay automatically provides SSL certificates for .local domains, but your OS may need you to trust ServBay’s User CA. Please refer to the ServBay documentation for details.

Frequently Asked Questions (FAQ)

Q: I edited files, but the website didn’t update?

A: Make sure you’re running vendor/bin/sculpin generate --watch in your project directory, and that the command hasn’t stopped due to an error. Check the terminal output for issues. Also, clear your browser cache or use private/incognito mode to view changes.

Q: SSL error when accessing https://servbay-sculpin.local?

A: ServBay generates self-signed certificates for .local domains. Your operating system needs to trust the ServBay User CA. Follow the instructions in the ServBay documentation to install and trust the CA certificate.

Q: How do I change the PHP version?

A: You can install and manage multiple PHP versions in ServBay under the "Packages" tab. Then, within the "Websites" tab, edit your Sculpin site configuration and select the desired PHP version before saving.

Q: What template engines and markup languages does Sculpin support?

A: Sculpin uses Twig for templating by default and provides extensive support for writing site content in Markdown.

Conclusion

Thanks to ServBay’s integrated environment, installing and configuring the Sculpin static site generator on macOS is straightforward. With pre-installed PHP and Composer, easy-to-configure web servers, and automatic SSL, ServBay lays a solid foundation for local Sculpin development. By following this guide, you can quickly set up your Sculpin environment and efficiently build and preview static site projects. Take advantage of Sculpin’s power and ServBay’s convenience to focus on creating high-quality content without spending hours configuring a complex development stack.