# Configure and initialize

Set environment values, initialize a fresh database and configure modules, reCAPTCHA and maps.

Edit `.env` privately. Set the real application URL and database credentials. The values below are placeholders:

```dotenv
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`:

```dotenv
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**:

```bash
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](https://czappstudio.com/ar/docs/administration/mail-storage-and-notifications#section-6). 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](https://czappstudio.com/ar/docs/installation/backups-and-updates). 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](https://czappstudio.com/ar/docs/installation/services#section-3) 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](https://docs.cloud.google.com/recaptcha/docs/create-assessment-website).

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](https://docs.cloud.google.com/recaptcha/docs/verify).

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](https://developers.google.com/recaptcha/docs/faq#im-using-content-security-policy-csp-on-my-website-how-can-i-configure-it-to-work-with-recaptcha) and keep the visible widget/badge and legal links intact.

Complete the [administrator activation test](https://czappstudio.com/ar/docs/administration/settings#section-3) 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.