Getting started

Prerequisites

• Docker and Lando 3.26 or newer. Lando runs the servers — nginx and PHP-FPM, MySQL 8.4, MariaDB 11.8, Redis, Mailpit, Node for the Vite dev server, and two worker services.
• On the host: PHP 8.5 with the extensions composer.json asks for, Composer 2 and Node 24. Everything a developer types runs there, through the wrappers in bin/.

The split is the whole idea: containers serve, the host works. A wrapper points the host’s PHP at the servers’ loopback ports and gets out of the way.

First run

lando start
cp .env.example .env
bin/composer install
bin/artisan key:generate
bin/artisan migrate:fresh --seed
npm install
npm run build

Set HILMS_ADMIN_PASSWORD in .env before seeding, otherwise the administrator account and the demo student are skipped. Locally the seeder also creates demo content: six categories, five instructors, 24 published and six draft courses with sections, lessons and sample blocks, a student with access to three of them, and a demo API client.

Where to go

What	URL
Public site	https://hilms.lndo.site
Admin panel	https://hilms.lndo.site/admin
Mail catcher	http://mail.hilms.lndo.site
Queues, performance, debugging	/horizon, /pulse, /telescope
Design catalogue	/design, with HILMS_DESIGN_CATALOGUE=true

Log in with HILMS_ADMIN_EMAIL (default [email protected]) and the password you set; the demo student is [email protected] with the same one. The panel uses the same login page as students.

Everyday commands

bin/pest                       the suite on MySQL 8.4, six processes
bin/pest-mariadb               the same suite on MariaDB 11.8
bin/gates                      every check on both engines, needed before any push
bin/pest app-modules/catalog/tests/Feature/CourseCatalogTest.php
bin/pest --filter=grants       a handful of tests, in one process
bin/stan                       PHPStan (Larastan, level 8)
bin/pint                       Pint (fix) — bin/composer lint:check only reports
bin/rector --dry-run           Rector dry run
bin/artisan migrate:fresh --seed
bin/composer install
bin/tree status                every git worktree, before you touch any of them
npm run build                  straight on the host, no wrapper

And the handful of things that belong to the containers:

lando start | lando stop | lando rebuild -y
lando dev                      Vite dev server with hot reload on http://localhost:5173
lando artisan optimize         warms the caches the site reads (never from the host)
lando horizon | lando queue    workers in the foreground
lando mysql | lando mariadb    a database shell as root

Front-end assets are built by default, so run npm run build after changing Blade or CSS — or keep lando dev running. Remember that student-facing Blade lives in themes/hilms/views, not in the modules.

Two rules the wrappers enforce for you: bin/pest names the tree’s own test database and never the one .env holds, and bin/artisan refuses optimize and config:cache, because the host reads no cache at all: the site’s caches are the container’s to warm, and the two sides never share one. Environment explains both.

Reading order

If you want to	Start at
Understand the shape of the codebase	Architecture
Add a feature	Modules and generators, then the chapter of the module it belongs to
Change how a student page looks	Theming
Write lesson or page content types	Blocks, then The block editor
Touch anything about access to a course	Learning
Work on pages, or on what the application links to	Pages
Work on menus	Navigation
Add a language, or touch anything an address or a phrase depends on	Languages
Store, show or accept a date	Time and clocks
Add something an administrator configures	Settings
Run it somewhere	Operations and docs/install/

Working with Claude Code

CLAUDE.md is the agent’s knowledge base and imports AGENTS.md, which Laravel Boost generates from the installed packages. .mcp.json starts Boost’s MCP server on the host (bin/host php artisan boost:mcp), so it serves the checkout the editor was opened in and survives a container rebuild. Run bin/artisan boost:update --discover after adding packages, and record durable project rules with Boost’s record-rule, which writes them into the committed .ai/rules.

HiLMS also exposes its own MCP server for authoring course material: bin/artisan mcp:start hilms-authoring (see API and agents and docs/install/mcp.md).