Octa — A modern WordPress boilerplate built on Bedrock, Sage/Acorn 6, Vite, Tailwind CSS 4 and Alpine.js
| Layer | Technology |
|---|---|
| CMS | WordPress 7.1 (Composer-managed) |
| PHP Framework | Acorn 6 (Laravel 13) |
| Structure | Bedrock |
| Templating | Blade |
| Bundler | Vite 8 |
| CSS | Tailwind CSS 4 |
| JS | Alpine.js 3, TypeScript |
| Docker | MariaDB 11.4, PHP-FPM 8.4, Nginx |
| CI | GitHub Actions |
- PHP >= 8.4
- Node >= 24
- Composer 2
- pnpm
- Docker (optional)
composer install
pnpm installcp .env .env.localEdit .env.local with your database credentials and site URL:
PROJECT_NAME='my-project'
DB_HOST='database'
DB_NAME='database_name'
DB_USER='database_user'
DB_PASSWORD='database_password'
WP_ENV='development'
WP_HOME='http://127.0.0.1:8000'
WP_SITEURL="${WP_HOME}/wp"With Docker:
docker compose up -dThe site is available at http://127.0.0.1:8000.
Without Docker:
Point your web server to the public/ directory and configure your local database, then update .env.local accordingly:
DB_HOST='localhost'pnpm devStarts the Vite dev server with HMR.
app/
├── Providers/ # Service providers (assets, theme)
└── View/
└── Composers/ # Blade view composers
bedrock/
├── application.php # WordPress bootstrap & config
└── environments/ # Per-environment overrides (development, staging)
config/ # Acorn config (theme, mail, prettify, post types…)
resources/
├── css/ # Tailwind CSS (app, editor, common)
├── js/ # TypeScript (app, editor)
├── views/ # Blade templates
├── fonts/
└── images/
public/
├── build/ # Vite output (manifest.json)
├── content/ # Plugins, mu-plugins, uploads
└── wp/ # WordPress core (never edit)
helm/ # Kubernetes Helm chart
routes/ # Custom route definitions
| Command | Description |
|---|---|
pnpm dev |
Vite dev server with HMR |
pnpm build |
Production build to public/build/ |
| Command | Description |
|---|---|
pnpm lint |
Lint JS/TS with ESLint |
pnpm lint:fix |
Auto-fix JS/TS lint errors |
composer lint |
Lint PHP with Laravel Pint (PSR-12) |
composer lint:fix |
Auto-fix PHP lint errors |
| Command | Description |
|---|---|
pnpm translate |
Generate .pot and update .po files |
pnpm translate:compile |
Compile .mo and JSON translations |
| Command | Description |
|---|---|
docker compose up -d |
Start stack (MariaDB + PHP + Nginx) |
docker compose down |
Stop stack |
Vite compiles resources/ to public/build/. The manifest is handled by AssetsServiceProvider. Path aliases available:
@scripts→resources/js@styles→resources/css@fonts→resources/fonts@images→resources/images
Theme supports, menus, and image sizes are configured in config/theme.php and registered by ThemeServiceProvider.
theme.json is auto-generated by @roots/vite-plugin from your Tailwind config and the base theme.json file.
Theme tokens (@theme) and styles shared by the front end and the block editor live in resources/css/common.css, imported by both app.css and editor.css. Put block styles there (or in files it imports) so the editor matches the front end.
Custom editor blocks, formats, variations, and plugins are registered from resources/js/editor/.
Declare custom post types and taxonomies in config/post-types.php. They are registered by Acorn Post Types with Extended CPTs, so every Extended CPTs argument is available.
Anonymous components live in resources/views/components/. <x-button> renders a link when given an href, a <button type="button"> otherwise, and accepts variant (primary, outline) and size (sm, base, lg).
Environment variables are loaded from .env (and .env.local override) via Dotenv in bedrock/application.php. Per-environment overrides live in bedrock/environments/.
All plugins are managed via Composer (wpackagist-plugin/*) and installed to public/content/plugins/. Never install plugins manually.
A persistent object cache is optional and driven by environment variables in bedrock/application.php:
| Environment | Result |
|---|---|
no REDIS_HOST |
Object cache disabled (WP_REDIS_DISABLED), the drop-in is inert |
REDIS_HOST |
Redis Object Cache (free, shipped by default) via WP_REDIS_* constants |
REDIS_HOST, Object Cache Pro installed |
Object Cache Pro via WP_REDIS_CONFIG, licensed with REDIS_TOKEN |
Optional variables: REDIS_PORT (default 6379), REDIS_DB (default 0), REDIS_PASSWORD, REDIS_PREFIX (defaults to WP_HOME without its scheme), REDIS_SCHEME. Any Redis-compatible server works (Redis, Valkey, managed services).
- Set
REDIS_SCHEME=tlswhen the server is reached over an untrusted network (managed Redis, another host), so the password and cached data are not sent in clear text. The certificate is verified against the system CA store. - Give each site its own Redis database or instance. With Redis Object Cache, a cache flush empties the whole database regardless of
REDIS_PREFIX; set theWP_REDIS_SELECTIVE_FLUSH=trueenvironment variable if several sites must share one database.
The production image copies the matching object-cache.php drop-in at build time. To use Object Cache Pro, add its private Composer repository and package (rhubarbgroup/object-cache-pro), then remove wpackagist-plugin/redis-cache.
With the Helm chart, valkey.enabled: true sets REDIS_HOST, and valkey.token additionally sets REDIS_TOKEN.
Octa ships without a custom fields plugin so it installs without any license. ACF Composer lets you declare fields, blocks and options pages as PHP classes (app/Fields, app/Blocks, app/Options). It needs one of:
ACF Pro (paid, full support)
composer config repositories.acf composer https://connect.advancedcustomfields.com
composer config --auth http-basic.connect.advancedcustomfields.com <license-key> <site-url>
composer require wpengine/advanced-custom-fields-pro log1x/acf-composer
wp acorn vendor:publish --tag="acf-composer"composer config --auth writes auth.json (git-ignored). In CI, store its content in a COMPOSER_AUTH_JSON secret and uncomment the matching step in .github/workflows/ci.yml. The Dockerfile already mounts it as a build secret.
Secure Custom Fields (free, wordpress.org)
composer require wpackagist-plugin/secure-custom-fields log1x/acf-composer
wp acorn vendor:publish --tag="acf-composer"Fields and options pages work. ACF Composer blocks do not render with SCF yet (Log1x/acf-composer#367).
PSR-12 enforced by Laravel Pint — see pint.json.
ESLint v9 with flat config — see eslint.config.js:
- Single quotes, no semicolons
- 2-space indent
- Trailing commas on multiline
.editorconfig ensures consistent formatting across editors (2-space for JS/JSON/YAML, 4-space for PHP).
| Service | Image | Port |
|---|---|---|
| database | mariadb:11.4 | 3306 (internal) |
| wordpress | wodby/wordpress-php:8.4 | — |
| frontend | wodby/nginx | 8000 |
| mailer | mailpit | 1025 / 8025 |
MariaDB data lives in the named volume db-data, prefixed with the Compose project name (the directory name by default), and survives docker compose down.
Stacks created before this volume existed kept their data in an anonymous volume, so the database starts empty after updating. To move the data over, before starting the stack, first record the old volume:
MOUNT='{{range .Mounts}}{{if eq .Destination "/var/lib/mysql"}}{{.Name}}{{end}}{{end}}'
OLD=$(docker inspect "${PROJECT_NAME}_database" --format "$MOUNT") && echo "Old volume: $OLD"Then recreate the database container on the new volume, copy the data and start the stack:
[ -n "$OLD" ] && docker compose up --no-start database \
&& NEW=$(docker inspect "${PROJECT_NAME}_database" --format "$MOUNT") \
&& [ -n "$NEW" ] && [ "$OLD" != "$NEW" ] \
&& docker run --rm -v "$OLD":/from:ro -v "$NEW":/to alpine cp -a /from/. /to/ \
&& docker compose up -dRun both with PROJECT_NAME exported (set -a; . ./.env; set +a). docker compose up --no-start creates the container without starting MariaDB, and the stack only starts once the copy succeeds. Keep the printed volume name: to retry, or if the old container was already removed (pick it from docker volume ls --filter dangling=true), set OLD=<volume> and run the second block again. The old volume is left untouched; remove it with docker volume rm "$OLD" once the site works.
GitHub Actions runs on every PR and push to main:
- PHP: Composer install +
pint --test - Node: pnpm install +
eslint+vite build
The Dockerfile provides a multi-stage production build:
- Node dependencies + Vite build
- Composer install (no-dev)
- Final image based on
inrage/docker-wordpress:8.4-redis
A Helm chart is available in helm/ for Kubernetes deployments.
.env files are never copied into the image: configure the container with environment variables. Set AUTH_KEY…NONCE_SALT to keep sessions stable across deployments; without them WordPress generates salts and stores them in the database. With the Helm chart, set app.tablePrefix when the database does not use the default wp_ prefix.
