Configure and initialize

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
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 sets where the Documentation link in the application footer points; set it to the Open Core HR documentation on the CZ App Studio website. APP_URL also controls password reset email links and passkey sign-in. Passkeys need HTTPS and are tied to the host name in APP_URL: people must open the application at that address, and changing the host name later stops existing passkeys from working, so everyone has to add theirs again. Configure outgoing mail in Settings → Mail before testing recovery. Set currency, timezone and formats in Settings → Localisation after installation.

Initialize a fresh database

Initialization uses command-line tools. Before running it, configure your own administrator in .env:

BOOTSTRAP_ADMIN_EMAIL=your-administrator-address
BOOTSTRAP_ADMIN_PASSWORD=your-own-password-of-at-least-12-characters
BOOTSTRAP_ADMIN_FIRST_NAME=Your
BOOTSTRAP_ADMIN_LAST_NAME=Name
APP_DEMO=false

There is no supplied production administrator password. On a new, empty database only:

php artisan migrate --force
php artisan db:seed --force
php artisan storage:link
php artisan optimize

The default seeder installs required system data and enabled-module defaults. It creates only your configured administrator and the system bot. It does not create demo employees, company scenarios or sample transactions, regardless of APP_DEMO. The bot has a dedicated role without browser or mobile portal access.

Keep access restricted while initializing. Verify administrator credentials, company settings and role/portal access before opening to employees. After initialization, remove BOOTSTRAP_ADMIN_PASSWORD from configuration and refresh the configuration cache. Existing administrator credentials are preserved when rerunning seeds, but fresh-install seeding is not an update procedure.

For a separate local demonstration database, php artisan demo:seed --fresh builds the Orionis Group demo company and connected sample activity. It wipes that configured database. The command is restricted to local/testing environments; never use a customer database for a demo. APP_DEMO controls demo interface behavior, not which data is seeded.

To add missing scenarios to an existing local demo without resetting it, run php artisan demo:seed --no-interaction from backend/. Existing demo payroll runs and payment history are preserved. With Payroll and its optional source modules enabled and a two-decimal deployment currency, Northstar · Integrated payroll demonstrates loan deductions, expense reimbursements, and a leaver's prorated salary plus approved Lifecycle adjustments. It includes full and partial payment, a reversed receipt, released reservations on a cancelled run, and a replacement draft. These sample runs capture their own integration choices; seeding does not change the administrator's Payroll settings.

When Payroll is enabled, the demo includes fixed-salary, manual-timesheet and attendance-review groups. Explore a published prior-month payroll with private payslips and payment history, a calculated manual run, and current drafts. Attendance exceptions remain available to practice reviewing source data. Demo payroll uses the configured currency and timezone; it does not send money or notifications.

Never reset a database, run migrate:fresh, re-run demo seeders or regenerate existing keys during updates.

Files and modules

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.

Configure durable file storage in Settings → Storage. New uploads use the active connection; existing files retain their original connection. Back up every referenced destination along with the database and application encryption key.

A super administrator manages installed modules in Settings → Modules. Open a module’s details to check its installed version, supported Core and mobile releases, and required modules before enabling it. The mobile version range describes compatibility; it does not report versions installed on employee devices.

Enable required modules first. A module cannot be enabled if its release is incompatible with the installed Core version. To disable a module that others depend on, disable those dependent modules first. Changes apply across the organisation, while user permissions still control access. Disabling a module preserves its records but makes it unavailable until enabled again.

This page manages packages already installed on the server. For package changes, follow the maintenance guide. Public documentation remains visible regardless of enabled modules; add-on module workflows are described in the Modules section.

Import & Export is a standard module. Its available data types depend on the requester's permissions and enabled source modules. Configure its queue worker and cleanup schedule before relying on bulk transfers.

Google reCAPTCHA

reCAPTCHA is a core feature configured in Settings → Security. It is disabled on installation. Do not put its runtime keys into .env; saved credentials are encrypted using the installation's APP_KEY. Preserve that key in protected backups.

For Google Cloud, enable the reCAPTCHA Enterprise API and create a Checkbox (v2) or Score-based (v3) website key for the selected version. Obtain a separate server API key restricted to that API and, where possible, your server's outbound IP addresses. Check assessment quotas and billing requirements in Google's setup guide.

For Classic, enter the matching site key and legacy secret key for the selected version. A Cloud API key cannot replace a legacy secret. See Google's SiteVerify guide.

Keep domain validation enabled in Google. Add the exact hostnames used to access this installation to the application's allowed-hostname list, and permit those domains in Google. Use separate development and live keys; allow localhost only in development keys. Do not activate Google's public testing keys on a live installation.

The server needs outbound HTTPS access to recaptchaenterprise.googleapis.com for Cloud verification or www.google.com/recaptcha/api/siteverify for Classic verification. Browsers must be able to reach Google's reCAPTCHA scripts and frames. If your reverse proxy adds a Content Security Policy, use Google's documented reCAPTCHA CSP configuration and keep the visible widget/badge and legal links intact.

Complete the administrator activation test with your own keys and domain. Automated tests cannot validate a customer's Google credentials or network.

Maps and customer place search

Maps are optional and are configured by an administrator in Settings → Maps, not in the environment file. Use two separate Google keys:

• Browser key draws the web maps (live tracking, route playback). Enable the Maps JavaScript API and restrict the key to your application's web addresses. A Map ID is optional.
• Server key powers customer place search. Enable the Places API and restrict the key to that API and your server's outbound IP addresses. It is stored encrypted and is never shown again after saving.

The server needs outbound HTTPS access to places.googleapis.com. Test search and selection on a customer form; the selected result should populate the address and coordinates. If the provider is unavailable, users can enter coordinates or capture their device location, and tracking information remains available as lists and timelines without the map.

The mobile app's map key is part of the mobile build configuration; see the mobile build guide.