Bedrock
#Requirements
Before running Statamic, you should ensure that your local machine has PHP and Composer installed. If you are developing on macOS, PHP and Composer can be installed via Homebrew. In addition, I recommend installing Bun for frontend dependencies.
The queue runs on Laravel Horizon, so you also need Redis. Use the Redis service in Herd Pro, or install it with brew install redis && brew services start redis.
#Installation
Using the Statamic CLI tool run the following command:
statamic new project_name jasonbaciulis/bedrock
- Navigate to the installed project folder:
cd project_name - Install frontend dependencies:
bun install - Create a Statamic user:
php please make:user - (Optional) install the MCP server and AI coding guidelines:
php artisan boost:install - Give the project a unique
APP_NAMEin.env(see Queues and Horizon) - Start Horizon, log tailing and Vite:
composer run dev
Recommended to use Herd for local dev.
Once you have started the development server with composer run dev, the website will be accessible in your web browser at https://bedrock.test. Head to https://bedrock.test/cp and use your email address and password to sign into the Statamic control panel.
#Tools, libraries and addons used in the project
- Statamic - Flat file Laravel CMS.
- TailwindCSS - Utility-first CSS framework.
- Alpine.js - Rugged, minimal tool for composing behavior directly in your markup.
- Embla - A lightweight carousel library with fluid motion and great swipe precision.
- Laravel Horizon - Redis queue workers with a dashboard at
/horizon. - Laravel Boost - Accelerates AI-assisted development by providing the essential context that AI needs to generate high-quality, Laravel-specific code.
- Statamic MCP - MCP (Model Context Protocol) server for Statamic that provides AI assistants with structured access to Statamic's capabilities through a modern router-based architecture.
#Views folder structure
resources/views/├── blocks/ # Page building blocks (Replicator fields)├── components/ # Project specific reusable components│ └── ui/ # Highly-reusable shadcn/ui style Alpine.js components│ └── form/ # Statamic form (create), field wrapper and shared form parts (label, error, instructions, etc.)│ └── fields/ # Form field types (custom Statamic form fields will require a snake_case view file here)├── partials/ # Template partials and fragments (things that aren't really reusable go here)├── sets/ # Content sets for Article Block└── errors/ # Error page templates
#Included blocks
- Article - Rich text with sets (picture, pull quote, table, video, FAQs, buttons).
- Blog Excerpt - The latest, featured or selected posts in a grid.
- FAQs - Accordion with FAQ structured data.
- Contact - Renders any Statamic form, with sections and conditional fields.
- Newsletter - Email opt-in form. Connect an email service provider before you use it (see Newsletter).
- Hero Demo - A hero that shows the UI components: form fields, tabs, dialog, dropdown, carousel and collapsible.
- Search Form - A search field that sends the query to the page that you select in "Results page".
- Search Results - Results from the
blogsearch index (config/statamic/search.php) in a grid, with pagination. - Style Guide - Shows the site grid, colors, buttons, alerts, headings and typography in one place.
#Blog
The Posts collection is mounted on the Blog page. The Blog page uses the Index blueprint and the posts/index template, which shows the page title, the text and all posts in a grid with pagination. The Limit field sets the number of posts per page. Posts use the posts/show template at /posts/{slug}.
#Tailwind CSS config
resources/css/config.css- The theme tokens (colors, fonts and other@themevalues), the Tailwind CSS plugins and the@configthat loadstailwind.config.js. Put the project's design tokens here.tailwind.config.js- Theprosestyles. The typography plugin is easier to configure in JS: it excludesnot-prosecontent from these styles, which CSS overrides must do by hand.
#Fonts
Bedrock loads Inter from Bunny Fonts, a privacy-friendly Google Fonts alternative.
To change the font:
- Change
fonts_urlinresources/views/layout.antlers.htmlto the stylesheet URL of the new font. Load only the weights that the site uses (400, 500, 600 and 700 by default). - Change
--font-sansinresources/css/config.cssto the new font family name.
To self-host a font, put the font files in resources/fonts, add an @font-face rule to a CSS file, and include the font's license file (for example OFL.txt) next to the font files.
#Newsletter
The Newsletter block posts the email address to /newsletter. Bedrock does not choose an email service provider for you, so app/Http/Controllers/SubscribeNewsletterController.php validates the email address and then returns 503 Service Unavailable with a message. The form shows that message. When a response has no message (for example, on a network error), the form shows the error message from the Newsletter global.
Visitors see the message text. Until you connect a provider, they see the "not configured" message, so connect one before you put the Newsletter block on a live page.
To connect a provider (for example Mailchimp, Kit or Buttondown):
- Add the API credentials to
.envand read them inconfig/services.php. Do not commit credentials. - In
SubscribeNewsletterController, send the email address to the provider's API. Return['success' => true]when the provider accepts it. When it fails, return['success' => false, 'message' => '…']with an error status. - Update
tests/Feature/NewsletterTest.php, and fake the HTTP request withHttp::fake().
Edit the title, text, button label, success message and error message in Globals → Newsletter.
#CLI commands
There is a nice list of custom scripts available in the command line to make a developer's job easier and more enjoyable.
#Blocks
Blocks are like LEGO bricks that provide you the maximum flexibility when building pages. Blocks are based on Replicator Fieldtype.
php please make:bedrock-block- Adds a set to the Blocks field.php please delete:bedrock-block- Removes a set from the Blocks field and all associated files.php please rename:bedrock-block- Renames a set inside Blocks and optionally moves to another group.
#Sets
Sets provide a powerful content creation experience with unparalleled flexibility for building entries i.e., Blog posts. Sets live in the the Article field which is based on Bard Fieldtype.
php please make:bedrock-set- adds a set to the Article.php please delete:bedrock-set- removes a set from the Article and all associated files.php please rename:bedrock-set- renames a set in the Article and optionally moves to another group.
#Dependency updates
Dependabot opens pull requests each Monday for Composer, Bun and GitHub Actions updates. It groups the minor and patch updates of each ecosystem into one pull request.
When CI passes on a Dependabot pull request that has only minor and patch updates, .github/workflows/dependabot-auto-merge.yml approves it and squash merges it. Major updates stay open for your review.
To make this work:
- In Settings → Actions → General, enable Allow GitHub Actions to create and approve pull requests.
- Open
https://github.com/<owner>/<repo>/settings/security_analysis(the gear Settings tab, then Advanced Security in the sidebar). Enable Dependency graph, Dependabot alerts and Dependabot security updates, in this order. Each one needs the one before it, and some can already be on. - A merge made with
GITHUB_TOKENdoes not start other workflows. If a workflow runs on push tomain(for example, a deploy), add agh workflow run <file> --ref mainstep after the merge step.
Security updates do not wait for Monday. When GitHub publishes an advisory for a locked Composer package or a GitHub Action, Dependabot opens a pull request immediately. The auto-merge workflow merges it when CI passes and it is a minor or patch update. Dependabot does not make security updates for Bun packages, so Bun packages get fixes only from the weekly version updates.
#Queues and Horizon
Horizon runs the Redis queue. Statamic uses the queue for Git commits, static cache warming and search index updates.
- Local:
composer run devstartsphp artisan horizon:listen, which restarts the workers when code changes. It uses thechokidarpackage for the file watcher. - Unique
APP_NAMEper project: Redis and Horizon key prefixes come fromAPP_NAME. Herd runs one Redis for all your local sites, so two projects withAPP_NAME=Bedrockshare one queue, and each project runs the other's jobs. - Dashboard access: in
localeveryone can open/horizon. In other environments, only Statamic super users can open it, or a request with theHORIZON_TOKENbearer token (see Horizon statistics in Ploi). - Metrics:
routes/console.phpscheduleshorizon:snapshotevery five minutes. The metrics graphs stay empty if the server does not run the Laravel scheduler. - Environments:
config/horizon.phpstarts workers only for theAPP_ENVvalues it lists (production,staging,local). If you add an environment, add it there too. If you do not, Horizon starts but processes no jobs. - Timeouts: keep the job
timeoutless than the supervisortimeout(60s), and the supervisortimeoutless thanREDIS_QUEUE_RETRY_AFTER(90s). If you do not, Redis gives a job that is still running to a second worker.
#Staging and production on the same server
When staging and production use one Redis instance, each site must use its own Redis databases. If they share a database, staging Horizon can run production jobs with staging code and content (for example, a Statamic Git commit job), and cache:clear on one site deletes the cache of the other.
| Variable | Production | Staging |
|---|---|---|
REDIS_DB (queue, Horizon) |
0 |
2 |
REDIS_CACHE_DB (cache, Stache) |
1 |
3 |
CACHE_PREFIX |
project_production_cache_ |
project_staging_cache_ |
HORIZON_PREFIX |
project_production_horizon: |
project_staging_horizon: |
Know these rules before you change this:
- Prefixes are not isolation. With the Redis cache store,
php artisan cache:clearcallsflushdb()and ignores every prefix. Only different database numbers keep the sites apart. The prefixes only make the keys easy to identify. - Each site uses two of the 16 Redis databases (0–15). A server can hold eight sites with the default Redis config. Give each site its own numbers.
- Never derive a Redis prefix from
base_path(). Ploi's zero-downtime releases live in timestamped folders, so the prefix changes on each deploy. The existing keys become orphans, and the web process and the queue workers stop sharing a cache.
#Production env file contents
Dump your .env values here with sensitive data removed. The following is a production example that uses full static caching:
APP_NAME=BedrockAPP_ENV=productionAPP_KEY=APP_DEBUG=falseAPP_URL= APP_LOCALE=enAPP_FALLBACK_LOCALE=en LOG_CHANNEL=stackLOG_STACK=singleLOG_DEPRECATIONS_CHANNEL=nullLOG_LEVEL=error DB_CONNECTION=sqlite SESSION_DRIVER=fileSESSION_LIFETIME=120SESSION_ENCRYPT=falseSESSION_PATH=/SESSION_DOMAIN=null BROADCAST_CONNECTION=logFILESYSTEM_DISK=localQUEUE_CONNECTION=redis CACHE_STORE=redisCACHE_PREFIX=project_production_cache_ REDIS_CLIENT=phpredisREDIS_HOST=127.0.0.1REDIS_PASSWORD=nullREDIS_PORT=6379REDIS_DB=0REDIS_CACHE_DB=1 HORIZON_PREFIX=project_production_horizon:HORIZON_TOKEN= MAIL_MAILER=smtpMAIL_HOST=MAIL_PORT=587MAIL_USERNAME=MAIL_PASSWORD=MAIL_ENCRYPTION=tlsMAIL_FROM_ADDRESS="hello@example.com"MAIL_FROM_NAME="${APP_NAME}" STATAMIC_LICENSE_KEY=STATAMIC_PRO_ENABLED=trueSTATAMIC_STACHE_WATCHER=falseSTATAMIC_STATIC_CACHING_STRATEGY=fullSTATAMIC_STATIC_WARM_INSECURE=trueSTATAMIC_TWO_FACTOR_ENABLED=trueSTATAMIC_REVISIONS_ENABLED=trueSTATAMIC_GRAPHQL_ENABLED=falseSTATAMIC_API_ENABLED=falseSTATAMIC_GIT_ENABLED=trueSTATAMIC_GIT_PUSH=trueSTATAMIC_GIT_DISPATCH_DELAY=1 STATAMIC_CUSTOM_CMS_NAME="${APP_NAME}"STATAMIC_CUSTOM_NAV_LOGO_URL='/assets/logos/logo-brand-fixed-white.svg'STATAMIC_CUSTOM_OUTSIDE_LOGO_URL='/assets/logos/logo-brand-fixed.svg' BEDROCK_CP_TOOLBAR_ENABLED=true
#NGINX config
When using full static caching strategy you will need to configure server rewrite rules.
To enable resource caching add the following to your NGINX config inside the server block:
expires $expires;
And this outside the server block:
map $sent_http_content_type $expires { default off; text/css max; ~image/ max; font/woff2 max; application/javascript max; application/octet-stream max;}
#Ploi deploy scripts (with zero-downtime enabled)
Ploi does not install Bun by default. Install Bun on your server before the first deploy.
#Horizon daemon
Add a daemon in Ploi for each site that runs php artisan horizon. With zero-downtime deploys, set the daemon directory to the site's current symlink, not to a release folder. If you do not, the daemon runs the old release after each deploy. The post deploy script below calls horizon:terminate, and the daemon then starts Horizon again with the new code.
#Scheduler
Enable the Laravel scheduler (php artisan schedule:run every minute) for each site. Horizon metrics need it.
#Horizon statistics in Ploi
Ploi can show Horizon statistics on the site page. Ploi's guide:
- Set
HORIZON_TOKENin the site's.envto a long random string. - In Ploi, open the site, go to Laravel → Settings, and enter the endpoint and the token.
HorizonServiceProvider already accepts this token as a bearer token.
#Pre deploy script
# Needed for Bun to workexport PATH="$HOME/.bun/bin:$PATH"
#Main deploy script
# Early Exit Checkif [[ {COMMIT_MESSAGE} =~ "[BOT]" ]]; then echo "Auto-committed on production. Nothing to deploy." {DO_NOT_NOTIFY} {CLEAR_NEW_RELEASE} exit 0fi cd {RELEASE} # Git & Dependenciesgit pull --rebase --autostash origin {BRANCH} {SITE_COMPOSER} install --no-interaction --prefer-dist --optimize-autoloader --no-dev --classmap-authoritative # Database (Safe Migration)if [ -f artisan ]; then {SITE_PHP} artisan migrate --forcefi # Frontend Buildbun install --frozen-lockfilebun run build # Laravel Optimization# We group these to minimize the window where the app is "naked"{SITE_PHP} artisan config:cache{SITE_PHP} artisan route:cache{SITE_PHP} artisan view:cache{SITE_PHP} artisan event:cache echo "⏳ Release prepared. Awaiting symlink switch…"
#Post deploy script
# Flush the PHP FPM worker{RELOAD_PHP_FPM} # Statamic Stache{SITE_PHP} artisan statamic:stache:clear{SITE_PHP} artisan statamic:stache:warm{SITE_PHP} artisan statamic:stache:doctor # Restart Horizon (the Ploi daemon starts it again with the new release){SITE_PHP} artisan horizon:terminate # Update all search indexes{SITE_PHP} artisan statamic:search:update --all # Static Caching{SITE_PHP} artisan statamic:static:clear{SITE_PHP} artisan statamic:static:warm --queue echo "🚀 Website deployed!"