Octa

<p align="center"> <img src="https://static.inrage.fr/octa/octa-wordpress.jpg" alt="Octa WordPress" /> </p> <p align="center"> <strong>Octa</strong> — A modern WordPress boilerplate built on Bedrock, Sage/Acorn 5, Vite, Tailwind CSS 4 and Alpine.js </p> <p align="center"> <a href="https://github.com/inrage/octa/actions"><img src="https://github.com/inrage/octa/actions/workflows/ci.yml/badge.svg" alt="CI"></a> <a href="LICENSE"><img src="https://img.shields.io/badge/license-MIT-blue.svg" alt="License"></a> </p>

---

Tech Stack

| Layer | Technology | |-------|-----------| | CMS | WordPress 6.9 (Composer-managed) | | PHP Framework | Acorn 5 (Laravel-style) | | Structure | Bedrock | | Templating | Blade | | Bundler | Vite 7 | | CSS | Tailwind CSS 4 | | JS | Alpine.js 3, TypeScript | | Docker | MariaDB 11.4, PHP-FPM 8.4, Nginx | | CI | GitHub Actions |

Requirements

• PHP >= 8.4
• Node >= 24
• Composer 2
• pnpm
• Docker (optional)

Getting Started

1. Install dependencies

composer install
pnpm install

2. Configure environment

cp .env .env.local

Edit .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"

3. Start the stack

With Docker:

docker compose up -d

The 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'

4. Development

pnpm dev

Starts the Vite dev server with HMR.

Project Structure

app/
├── Providers/              # Service providers (assets, blocks, theme)
└── View/
    └── Composers/          # Blade view composers
bedrock/
├── application.php         # WordPress bootstrap & config
└── environments/           # Per-environment overrides (development, staging)
config/                     # Acorn config (theme, ACF, mail, prettify…)
resources/
├── css/                    # Tailwind CSS (app, editor, blocks/)
├── 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

Commands

Development

| Command | Description | |---------|------------| | pnpm dev | Vite dev server with HMR | | pnpm build | Production build to public/build/ |

Linting

| 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 |

i18n

| Command | Description | |---------|------------| | pnpm translate | Generate .pot and update .po files | | pnpm translate:compile | Compile .mo and JSON translations |

Docker

| Command | Description | |---------|------------| | docker compose up -d | Start stack (MariaDB + PHP + Nginx) | | docker compose down | Stop stack |

Architecture

Assets

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 Configuration

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.

Blocks

Block-specific CSS goes in resources/css/blocks/ and is dynamically enqueued by BlockAssetsServiceProvider.

Custom editor blocks, formats, variations, and plugins are registered from resources/js/editor/.

Environment Config

Environment variables are loaded from .env (and .env.local override) via Dotenv in bedrock/application.php. Per-environment overrides live in bedrock/environments/.

WordPress Plugins

All plugins are managed via Composer (wpackagist-plugin/*) and installed to public/content/plugins/. Never install plugins manually.

Code Style

PHP

PSR-12 enforced by Laravel Pint — see pint.json.

JavaScript / TypeScript

ESLint v9 with flat config — see eslint.config.js:

• Single quotes, no semicolons
• 2-space indent
• Trailing commas on multiline

Editor

.editorconfig ensures consistent formatting across editors (2-space for JS/JSON/YAML, 4-space for PHP).

Docker Services

| Service | Image | Port | |---------|-------|------| | database | mariadb:11.4 | 3306 (internal) | | wordpress | wodby/wordpress-php:8.4 | — | | frontend | wodby/nginx | 8000 | | mailer | mailpit | 1025 / 8025 |

CI/CD

GitHub Actions runs on every PR and push to main:

• PHP: Composer install + pint --test
• Node: pnpm install + eslint + vite build

Deployment

The Dockerfile provides a multi-stage production build:

1. Node dependencies + Vite build
2. Composer install (no-dev)
3. Final image based on inrage/docker-wordpress:8.4-redis

A Helm chart is available in helm/ for Kubernetes deployments.

License

MIT - inRage