Forkiva Docs

Installing Forkiva for developers ​

Forkiva is one Laravel application with an integrated Vue 3 interface. The Laravel application directory is the only working directory for Composer, Yarn, development, builds, and deployment.

The application directory is named forkiva/. It is the application root and contains artisan, composer.json, package.json, Modules/, resources/, and public/.

1. Requirements ​

Review System Requirements before installing. In particular, use PHP 8.4 for the browser installer and a Node.js version accepted by package.json.

The Forkiva package must include every enabled module before dependencies are installed or assets are built.

2. Install dependencies ​

Run all commands from the Laravel application root:

bash
cd forkiva
composer install
yarn install --frozen-lockfile
yarn check:modules

Forkiva uses Yarn Classic and yarn.lock. Do not create a second package.json, node_modules/, or npm lockfile for the Vue application.

3. Create the environment file ​

For a new installation only:

bash
cp .env.example .env
php artisan key:generate

On Windows Command Prompt, use copy .env.example .env.

Configure the database, mail, cache, queue, storage, and application URL in this single .env file. Never replace an existing .env or run key:generate for an installed system; changing APP_KEY can invalidate encrypted application data.

If passkeys are enabled, set PASSKEYS_RELYING_PARTY_ID and PASSKEYS_ALLOWED_ORIGINS for the Laravel browser URL that users actually open—not Vite's port 3101.

Vue build variables ​

The Vue build reads its VITE_* values from the same Laravel .env:

dotenv
VITE_STORAGE_ENCRYPT_ALL=false
VITE_STORAGE_ENCRYPTION_KEY=replace-with-a-stable-random-value
  • VITE_API_URL is not needed for the normal integrated deployment. The browser uses same-origin /api and the API functions continue to call /v1/... paths.
  • VITE_STORAGE_ENCRYPTION_KEY enables encryption for sensitive browser-storage records. Set VITE_STORAGE_ENCRYPT_ALL=true only if all supported storage records should be encrypted.
  • Generate a deployment-specific value with php -r 'echo base64_encode(random_bytes(32)), PHP_EOL;', then store it in your environment manager.
  • Keep the value stable between builds. Changing it makes existing encrypted browser records unreadable and users will need to sign in again.
  • Every VITE_* value is compiled into browser JavaScript and is public. Never put a server password, Laravel APP_KEY, API token, or other secret in it.

Restart Vite after changing a VITE_* value. Production values must exist in the build environment when yarn build runs.

4. Start the complete development application ​

Use either of these equivalent commands:

bash
composer run dev
bash
yarn dev

The command starts Laravel, Vite, the queue listener, and the Laravel scheduler together. Open the Laravel address printed in the terminal, normally:

text
http://127.0.0.1:8000

Do not open http://localhost:3101 as the application. Port 3101 is Vite's development asset server, so it correctly shows the Laravel + Vite information page when opened directly.

If Laravel Herd or another web server already serves the application, run only the asset server:

bash
yarn dev:assets

5. Complete a new installation ​

With APP_INSTALLED unset or false, open the Laravel URL. Forkiva redirects to:

text
http://127.0.0.1:8000/installer

Use the wizard to verify the server, configure an empty database, optionally add demo data, and create the first administrator. The wizard runs module migrations and seeders, creates the storage link, and writes APP_INSTALLED=true after completion.

The installer records production-safe APP_ENV and APP_DEBUG values. For a local development machine, change them back after installation:

dotenv
APP_ENV=local
APP_DEBUG=true

Then restart the development command. Do not use fixed default administrator credentials; use the account created in the installer.

6. Existing installations ​

For an existing database, preserve .env, APP_KEY, uploaded files, and browser storage configuration. Install the new dependencies, build the assets, back up the database, and follow Upgrading Forkiva. Do not run the new-installation wizard or module seeders over production data.

7. Validation ​

Before creating a release, run:

bash
yarn check:modules
yarn test
yarn lint
yarn format:check
yarn build
composer test

Run database-engine-sensitive tests against an explicitly disposable MySQL test database. A passing Vue build does not prove that migrations, queues, scheduled jobs, PDF generation, storage, mail, or every API workflow is production-ready.

8. Production deployment ​

Build and deploy one Laravel release containing the application code and public/build/. Point the web server document root to the application's public/ directory and route non-file requests to public/index.php.

Production rules:

  • Run composer install --no-dev --prefer-dist --optimize-autoloader for PHP runtime dependencies.
  • Install JavaScript development dependencies in the build environment, then run yarn check:modules and yarn build.
  • Retain the production Node dependencies and Puppeteer's compatible Chrome runtime on any worker that renders PDFs or receipts.
  • Run managed Laravel queue workers and configure the scheduler as described in Running the Forkiva Schedule.
  • Serve the application over HTTPS with APP_DEBUG=false.
  • Do not run Vite, yarn dev, php artisan serve, or composer run dev in production.
  • Deploy Laravel code and generated assets atomically. Do not replace public/ wholesale because it also contains application assets and the storage link.

The Flutter driver and employee applications remain separate mobile builds. They are not installed with Composer or Yarn, but their API base URLs must point to this same compatible Laravel deployment.

Tenvoro

Copyright © Tenvoro