Installation & Administration
Version 1.0.0 ยท 2026-10-10
Release preparation
Online: https://docs.opencorehr.com
Version 1.0.0 ยท 2026-10-10
Release preparation
Online: https://docs.opencorehr.com
This guide is for the person installing and maintaining Open Core HR. For everyday HR and employee tasks, open the User Manual.
Open Core HR is a self-hosted Laravel application supplied with source code. Its marketing and documentation sites can run on Cloudflare; the HR application needs a PHP application server and database.
This guide accompanies version 1.0.0 in release preparation. These deployment recipes are checked against repository configuration. Fresh installations on the named hosting platforms still need verification before those platforms are advertised as supported.
Keep third-party licence notices with the installation. Use the final purchase package for customer licence and support terms.
| Component | Requirement |
|---|---|
| PHP | 8.4 or a compatible later version accepted by the supplied Composer lockfile |
| Composer | 2.x; verify with composer check-platform-reqs --no-dev |
| PHP extensions | All extensions required by composer.lock; commonly curl, PDO/MySQL, zip, mbstring, XML/DOM, fileinfo and OpenSSL |
| Database | MySQL; choose a maintained version and validate migrations on that exact version |
| Web server | Nginx or Apache with its document root set to backend/public |
| Frontend build | Node.js compatible with the locked Vite dependencies; use Node 22 LTS for the build environment |
| Background services | A scheduler every minute and a persistent worker for asynchronous jobs |
| HTTPS | Required for a customer-facing deployment |
| Real-time features | Persistent Reverb process and WebSocket proxy when enabled |
The backend README's MySQL 5.7 and Node 18 entries are historical minimums, not a current hosting recommendation. The supplied lockfiles and target-platform validation are authoritative.
| Platform | Confirm with the provider |
|---|---|
| Linux VPS | Compatible PHP/CLI, database, SSH, cron, web server and process manager |
| cPanel / Plesk | Compatible web and CLI PHP, Composer/SSH, configurable document root, cron and persistent workers |
| Shared hosting | All requirements above; many plans cannot run workers or WebSockets |
| Windows / IIS | PHP/MySQL compatibility, URL rewriting, scheduling and service management; separate acceptance required |
Prefer a VPS for live chat, calls and other real-time features. Cloudflare DNS/proxy does not provide a PHP runtime or MySQL database.
Fresh-installation acceptance on cPanel, Linux VPS, Plesk/Apache and Windows remains pending. Local regression tests do not certify these hosting environments.
backend/. Run application commands from that directory.hr.example.com, to the application server.backend/public.Do not expose the repository root, .env, source, backups or private uploads through the public document root.
cd backend
composer install --no-dev --prefer-dist --optimize-autoloader
composer check-platform-reqs --no-dev
npm ci
npm run build
Use the supplied lockfiles. If Node.js is unavailable on the server, build on a trusted machine and upload the matching public/build with the release source. Do not deploy a development public/hot file. Composer dependencies must match the server's PHP platform.
On a new installation only:
cp .env.example .env
php artisan key:generate
php artisan jwt:secret
Continue with configuration. Do not overwrite an existing .env or regenerate encryption/authentication keys during updates.
This recipe requires compatible web/CLI PHP, Terminal/SSH, Composer, cron and persistent worker support. cPanel alone does not guarantee these capabilities.
public_html, for example /home/account/open-core-hr/backend./home/account/open-core-hr/backend/public.backend, and follow preparation and configuration./path/to/php /home/account/open-core-hr/backend/artisan schedule:run >> /home/account/open-core-hr/backend/storage/logs/scheduler.log 2>&1
Use the provider's actual compatible PHP binary. Monitor and rotate this log. Ask the provider to supervise queue:work and Reverb if needed; see services.
If the host cannot set public as the document root or run required services, use a compatible plan or VPS. Moving the front controller into a public repository root is not an approved workaround.
Finish the installation checklist. cPanel acceptance remains pending.
Use a maintained Linux distribution. Install Nginx, compatible PHP-FPM/CLI and extensions, MySQL, Composer and a process manager using supported packages. Package names and socket paths vary by distribution.
/srv/open-core-hr/backend or your chosen private path.storage and bootstrap/cache. Keep source and secrets private; do not use world-writable permissions.server {
listen 80;
server_name hr.example.com;
root /srv/open-core-hr/backend/public;
index index.php;
client_max_body_size 20m;
location / {
try_files $uri $uri/ /index.php?$query_string;
}
location ~ ^/index\.php(/|$) {
include fastcgi_params;
fastcgi_param SCRIPT_FILENAME $realpath_root$fastcgi_script_name;
fastcgi_pass unix:/run/php/php8.4-fpm.sock;
fastcgi_hide_header X-Powered-By;
}
location ~ \.php$ { return 404; }
location ~ /\.(?!well-known).* { deny all; }
}
Align upload limits in PHP, Nginx and application validation. This starting configuration still needs acceptance on the exact Linux/PHP stack.
These environments require their own fresh-installation checks before being advertised as supported.
Create the application domain, select compatible PHP for web and CLI, set its document root to backend/public, create its database and enable SSL. Use SSH for preparation and configuration. Configure Scheduled Tasks for artisan schedule:run every minute. Arrange persistent queue/Reverb services with the hosting provider.
Set DocumentRoot to backend/public. Enable mod_rewrite, permit the supplied public/.htaccess rules, configure compatible PHP and HTTPS, and deny access to hidden files. Follow common setup and services instructions. If only the homepage works, check rewriting and virtual-host settings.
Install compatible PHP/extensions and MySQL. Set the site root to backend/public. Configure IIS URL Rewrite rules equivalent to the Apache front controller; IIS does not read .htaccess. Adapt Unix commands for PowerShell. Use Task Scheduler for the scheduler and supervised Windows services for queue workers and Reverb. Verify filesystem permissions and storage links.
Windows production hosting is not currently certified by this guide. Arrange deployment-specific validation or use the VPS recipe.
Install compatible PHP, Composer, MySQL and Node.js. Use a separate local database with demonstration data only.
Follow preparation, using composer install with development dependencies instead of --no-dev. Set APP_ENV=local, configure a new local database, and follow configuration.
# Terminal 1, from backend
php artisan serve --host=127.0.0.1 --port=8000
# Terminal 2, from backend
npm run dev
Set APP_URL=http://localhost:8000. Run additional services when testing asynchronous or real-time features. Use local mail capture instead of customer email accounts.
Use a real web server and compiled assets for customer hosting. Keep local configuration and uploads out of source packages.
Edit .env privately. Set the real application URL and database credentials. The values below are placeholders:
APP_ENV=production
APP_DEBUG=false
APP_DEMO=false
APP_URL=https://hr.example.com
APP_TIMEZONE=UTC
TELESCOPE_ENABLED=false
DB_CONNECTION=mysql
DB_HOST=127.0.0.1
DB_PORT=3306
DB_DATABASE=your_database
DB_USERNAME=your_database_user
DB_PASSWORD=your_private_password
QUEUE_CONNECTION=database
CACHE_STORE=file
SESSION_DRIVER=file
DOCUMENTATION_URL=https://docs.opencorehr.com
APP_URL also controls password reset email links. Configure SMTP before testing recovery. Review locale defaults in .env.example; manage company localization in the app after installation.
The current initialization uses command-line tools, with no browser installer. On a new, empty database only:
php artisan migrate --force
php artisan db:seed --force
php artisan storage:link
php artisan optimize
Review the supplied seeders and enabled modules before customer use. Current seeders create a known demonstration administrator (superadmin@demo.com, password 123456) and can include module fixtures. APP_DEMO=false disables the optional demo seeder; it does not remove every sample record or change this password.
Keep access restricted while initializing. Immediately change the administrator email/password, review seeded data, and verify role/portal access before opening to employees. A secure customer bootstrap and clean seed-data audit remain release acceptance items.
Never reset a database, run migrate:fresh, re-run demo seeders or regenerate existing keys during updates.
The web process needs write access to storage and bootstrap/cache. Keep private documents private; do not link all of storage publicly. Use authorized application downloads.
Review optional features in Modules. Disabling a module changes app availability; its public documentation remains visible and labels the required module.
Configure the provider's SMTP host, port, credentials and sender address in private configuration. Match transport/encryption settings to the supplied config/mail.php. Verify the sender domain and test real inbox delivery. log and array mailers do not deliver email.
Test password recovery and confirm the email link opens the reachable HTTPS application hostname.
For a database queue, apply its migrations and supervise a worker from backend:
php artisan queue:work --sleep=3 --tries=3 --timeout=90
Ensure queue retry_after exceeds the worker timeout. Run with access to storage/configuration. Use systemd, Supervisor or the host's worker manager to restart on failure and reboot. After code deployment:
php artisan queue:restart
php artisan queue:failed
The sync queue runs jobs inline; it does not demonstrate asynchronous worker health.
Add a cron entry every minute:
* * * * * cd /srv/open-core-hr/backend && /path/to/php artisan schedule:run >> /srv/open-core-hr/backend/storage/logs/scheduler.log 2>&1
Replace paths, monitor/rotate logs, review php artisan schedule:list and confirm timezones. Modules can contribute additional schedules when enabled.
Configure REVERB_* and public VITE_REVERB_* before building assets. Keep private Reverb secrets out of frontend variables. Supervise php artisan reverb:start and configure HTTPS/WSS proxying with WebSocket upgrade headers. Restart long-running services after configuration changes.
Microsoft 365, Firebase and other external providers need customer-owned credentials and separate live acceptance. Do not ship configured service accounts.
Record product version, hosting platform, PHP/database versions, date and outcome. Complete before inviting employees:
backend/public is served.Documentation publication is separate from customer-installation acceptance, secure bootstrap review and live integration verification.
Back up the database, private/uploaded files, .env, encryption/OAuth keys, module settings and customizations. Encrypt backups, restrict access, retain an off-server copy and test restoration in isolation. Do not send production backups to support.
.env, storage and existing keys.backend:php artisan down
composer install --no-dev --prefer-dist --optimize-autoloader
php artisan migrate --force
php artisan optimize
php artisan queue:restart
php artisan up
Do not run fresh-install seeders unless the release explicitly requires a reviewed data upgrade. Reverting source alone does not reverse database changes; follow the tested restore/rollback plan.
Start with company details, localization, roles, approval workflows and module settings. See the User Manual's settings overview and roles and permissions.
For source changes, keep a private version-controlled copy, document changes and re-test after updates. Keep business rules in the backend and use the shared API across clients. Rebuild assets after changing frontend source/public configuration. Never put secrets in VITE_* variables.
Provider integrations require customer accounts, permissions and their own costs. Enable only configured and tested integrations. Distribute examples rather than customer credentials.
For employee-app source builds, use apps/employee/README.md in the matching release. Signing, store publication and physical-device acceptance are separate tasks.
Read storage/logs and web/PHP logs privately. Check PHP compatibility, dependencies, database credentials, keys and writable storage/cache. After configuration changes, run php artisan optimize and restart services. Keep public debug mode off. Share sanitized errors only.
Build the matching frontend source and deploy public/build. Remove a development public/hot file. Check document root, asset URLs and browser errors.
Check Nginx try_files, Apache rewriting or IIS URL Rewrite. The root must be backend/public.
Check APP_URL, HTTPS, sessions, application key, writable session storage and cookies. Clear stale cookies after correcting the hostname. Check account status and roles if the wrong portal opens.
Verify SMTP/sender domain, spam folders, queue workers and failed jobs. A log mailer does not deliver. Confirm reset links use the reachable application hostname.
Check storage permissions, disk settings and PHP/server limits. Private files require authorized downloads. Do not expose private storage to work around authorization errors.
Check module enablement, Reverb, WSS hostname, proxy upgrade headers and firewalls. Rebuild after VITE_REVERB_* changes. Shared hosting may lack persistent WebSocket support.
Only with a secure provider equivalent for Composer, Artisan, scheduling and workers, validated on that host. Uploading files does not initialize the database.
Cloudflare hosts the static marketing/docs sites. This Laravel app still needs a PHP server and database.
The manual covers optional modules and different roles. Ask the administrator to check enablement/permissions. Documentation does not grant access.
Use the support channel supplied with your purchase or final listing. Include version, platform, PHP/database versions, sanitized errors, reproduction steps and the failing guide step. Do not send credentials, employee records or production databases.
Installation, customization, infrastructure and mobile publication services are scoped according to purchased terms. This guide does not promise a support period or service entitlement.
Open Core HR is a commercial self-hosted product supplied with source code. Customer terms are being finalized. Use the licence included with your purchase and applicable marketplace terms. Third-party components retain their own licences.
The product uses Laravel, React, Inertia, Flutter and dependencies in its Composer/npm/pub lockfiles. Retain their supplied notices. The dependency list is not a completed redistribution audit; release acceptance must confirm included assets and rights.
Documentation tooling uses Markdown-it, YAML, Playwright and Cloudflare Workers. The locally served Inter font includes its licence.