Skip to main content

Local development

This guide gets a working OpenHR PH environment on your machine.

Requirements​

ToolVersionNotes
PHP8.3 or newer8.4 is also supported; enable bcmath, gd, intl, mbstring, pdo_mysql, zip
Composer2.x
Node.js22.xVite 8 needs a modern Node release
npm10.x or newer
MySQL8.xProduction database; SQLite is used by tests
Go1.24.xOnly needed for the payroll engine
GitAny recent version

Optional: Redis for cache/queues, Laravel Reverb for WebSockets, and Playwright browsers for E2E tests.

1. Clone and install PHP dependencies​

git clone https://github.com/kawayanmedia/openhrph.git
cd hris

composer install
cp .env.example .env
php artisan key:generate

If php is not on your PATH, use the absolute path to your PHP binary for the commands below.

2. Create the database​

Create a MySQL database:

mysql -u root -p -e 'CREATE DATABASE hris CHARACTER SET utf8mb4 COLLATE utf8mb4_unicode_ci;'

Set the DB_* values in .env:

DB_CONNECTION=mysql
DB_HOST=127.0.0.1
DB_PORT=3306
DB_DATABASE=hris
DB_USERNAME=root
DB_PASSWORD=

Apply the migrations:

php artisan migrate --force

The migrations in database/migrations create the full schema, including the optional Filament tables. They are guarded with Schema::hasTable and Schema::hasColumn, so rerunning them on an existing development database only applies the outstanding changes.

The automated test suite uses in-memory SQLite via phpunit.xml; you do not need a separate test database for the default suite.

3. Configure the installation​

Ask the installer whether the whole installation serves Government or Private organisations and which country's payroll rules it uses:

php artisan openhr:install

The command also imports the selected country's statutory schedule. It is idempotent for inspection but refuses a second run unless you pass --force. For automation:

php artisan openhr:install \
--sector=Private \
--country=PH \
--currency=PHP \
--locale=en_PH \
--timezone=Asia/Manila \
--no-interaction

The sector is locked installation-wide: existing companies are updated and every company created later inherits it. The country lives in installation_settings; add a new jurisdiction to config/payroll.php before selecting it.

4. Create your admin account​

php artisan admin:create

The command asks for a name, email, password, and company name. It creates the company, the owner user, and the company membership. It never prints the password.

You can pass options for automation:

php artisan admin:create \
--name="Local Admin" \
--email=admin@example.com \
--password='change-me-now' \
--company-name="Local Company" \
--no-interaction

Use --force to update an existing user with the same email.

The default db:seed seeds a demo tenant with an admin@example.com / password login plus the default organization, payroll and statutory reference data. The seeders are idempotent, so running php artisan db:seed --force again is safe.

Sector-specific seeding follows installation_settings.sector, which php artisan openhr:install writes:

SectorWhat db:seed adds
Not configured (default)The full default data set, including the Government salary schedule and plantilla items, so you can try either sector
GovernmentThe same default set plus the DBM salary schedule and plantilla items; the NWPC wage orders are skipped
PrivateNo salary grades or plantilla items; the PH statutory tables and NWPC wage orders are imported

The shared catalogues (leave_types, compensations) are seeded once for the whole installation. A company sees the shared rows plus its own overrides; the sector column decides which sector-only rows it sees. Use admin:create when you need a different owner account.

5. Build front-end assets​

npm ci
npm run build

For development with hot reload:

npm run dev

If you see “Unable to locate file in Vite manifest”, run npm run build or start npm run dev.

6. Build the payroll engine​

make -C payroll-engine build
php artisan payroll:engine --check

The binary is written to bin/payroll-engine (git-ignored). Useful environment variables:

VariablePurpose
PAYROLL_ENGINE_BINARYOverride the binary path
PAYROLL_ENGINE_DSNOverride the MySQL DSN
PAYROLL_ENGINE_DRIVERgo (default) or php for the fallback
PAYROLL_ENGINE_INLINE_THRESHOLDEmployee count below which payroll runs inline (default 50)
PAYROLL_ENGINE_TIMEOUTProcess timeout in seconds (default 600)

db:seed imports the effective-dated statutory tables through payroll:statutory:import and the 2026 holiday calendar through payroll:holidays:import. To refresh them manually, run php artisan payroll:statutory:import --country=PH after migrating. Use --fresh only when you intend to replace that country's statutory rows. For a country without a built-in driver, import a component definition with php artisan payroll:statutory:import --country=XX --file=path/to/components.json.

7. Run the application​

The fastest option is the Composer dev script, which starts the HTTP server, queue listener, log viewer, and Vite together:

composer run dev

Or run the pieces yourself:

php artisan serve
php artisan queue:work
php artisan schedule:work
npm run dev

Open http://127.0.0.1:8000/app/login. The .env.example uses http://localhost:8000 for the app and http://portal.localhost:8000 for the employee portal; modern browsers resolve *.localhost to loopback.

8. Storage and caches​

php artisan storage:link
php artisan optimize:clear

If uploaded files do not appear, check storage/app/public, the public/storage symlink, and the FILESYSTEM_DISK/MEDIA_DISK values.

Desktop build​

The repository also ships a NativePHP desktop build. It does not use MySQL, the Go payroll binary, or the scheduler/queue commands above. Run it in a native window with:

php artisan native:install # first time only: Electron deps + bundled PHP binary
php artisan native:run

The desktop runtime uses database/nativephp.sqlite in development and applies App\Services\Desktop\DesktopEnvironment only inside Electron. The first window opens the setup wizard at /setup; outside Electron that route returns 404. Use php artisan native:migrate, native:migrate:fresh, and native:reset for its database and build files. See Desktop app for packaging, signing, and auto-updates.

Queues and realtime​

The default queue is the database queue:

php artisan queue:work --sleep=3 --tries=3

The scheduler:

php artisan schedule:work

Reverb is optional. To enable broadcasting, configure the REVERB_* variables, set BROADCAST_CONNECTION=reverb, run php artisan reverb:start, and proxy WebSockets through your web server.

Try the demo sign-up flow locally​

Set DEMO_MODE=true in .env and open http://127.0.0.1:8000/register. The default mailer in .env.example points at a local Mailpit instance on 127.0.0.1:1025; run Mailpit (or read storage/logs/laravel.log when MAIL_MAILER=log) to open the verification link.

Each sign-up creates an isolated company with sample employees, timesheets, and an open payroll. Leave DEMO_MODE=false on any installation that holds real payroll data: with demo mode off, /register and the verification routes return 404.

Tests​

vendor/bin/pest
make -C payroll-engine test
npm run e2e
npm run e2e:dark

See Testing for the full workflow.

Common commands​

php artisan route:list --path=app
php artisan about
php artisan config:show admin
php artisan payroll:preview 24
php artisan payroll:statutory:import
php artisan testing:seed-e2e-company
php artisan testing:purge-e2e-company

Troubleshooting​

If something fails during setup, read Troubleshooting. The most common causes are the PHP extensions, the database import order, the Vite manifest, and the payroll binary path.