Local Development

This page is for working on Evolve itself: the core, the modules, the panel, or the base theme. If you are building a website with Evolve, start with Installation instead.

Development happens directly in the racerfish/evolve-cms repository. The package boots, tests, and demos itself through an Orchestra Testbench workbench. There is no separate host application to install.

Quick start

git clone https://github.com/racerfish/evolve-cms.git
cd evolve-cms

composer update
vendor/bin/testbench workbench:build   # publish assets, create sqlite, migrate, seed
composer workbench:theme               # build the frontend theme (requires Node)
vendor/bin/testbench serve             # http://127.0.0.1:8000

serve opens the browser session already authenticated as the seeded admin and lands on the panel at /evolve. To log in manually use web@racerfish.com with the password password.

Everything runs on a local sqlite database inside the Testbench skeleton. Nothing external is required: media uses generated placeholder images, the Shopify demo store renders from locally seeded data, and no API keys are needed for the core experience.

What the demo installation contains

workbench:build seeds a complete demo site, so every part of the CMS can be exercised immediately:

• Kitchen Sink. A page containing one block for every shipped blueprint, with sample content in all field types, nested child blocks in the container blocks, and placeholder images wired through the media pipeline. Use it to verify both panel editing and frontend rendering when you change a blueprint, a field type, or a theme component.
• Module demo content. A company team with members and a job posting, blog posts with categories and covers, events with a participant, FAQs, locations, projects, and a Shopify store with three products.
• Overview pages. The main navigation carries one page per module (Blog, Events, Team, Jobs, Standorte, Shop), each built from the standard hero block plus the module's published list block. These pages double as living reference implementations for the module blocks.

Rebuild the database and demo content at any time:

vendor/bin/testbench workbench:build

Day-to-day commands

Command	Purpose
vendor/bin/testbench serve	Serve panel and frontend
vendor/bin/testbench workbench:build	Reset and reseed the demo installation
composer workbench:theme	Rebuild the frontend theme into the workbench
vendor/bin/phpunit	Run the full test suite
vendor/bin/phpunit --testsuite Harness	Standalone boot smoke test

Two things to remember after a composer update: run composer dump-autoload if you pulled changes that touch composer.json, and re-run composer workbench:theme, because the theme build output lives inside the Testbench skeleton in vendor/ and is wiped with it.

How the workbench relates to real installations

Real installations carry configuration in published files (config/livewire.php, config/auth.php, published blueprints, the published theme). The workbench provides the same wiring from the package sources instead, in workbench/app/Providers/WorkbenchServiceProvider.php: blueprints load straight from the module app-publish directories, theme views resolve from the package theme, and required settings such as legacy_model_binding are applied. The test suite boots through the same provider, so tests, the served workbench, and production installations share one configuration surface.

This also means blueprint and theme edits in the package are reflected live in the served workbench, without a publish step.

Tests and CI

The suite runs on an in-memory sqlite database and covers the core, blog, Shopify, and MCP modules. CI runs the full suite plus Pint on every pull request and every push to master. A pull request is expected to be green before review.

Contributing and releases

• Every pull request carries exactly one semver:major, semver:minor, or semver:patch label. Security fixes add security.
• Releases are cut in batches. The version bump is the highest semver label since the last tag, and release notes are generated from the merged pull request titles.
• GitHub Releases is the changelog of record. The Release History page in these docs is a condensed copy, updated as part of each release.

The full process lives in RELEASING.md in the package repository.