Skip to main content

​
Requirements

RequirementVersion
PHP8.2+
Composer2
Node.js20 (LTS recommended)
npm10+
DatabaseMySQL 8.0+ / MariaDB 10.6+ or SQLite
Redis6+ (optional — required for sessions and queues in production)
Web serverNginx (production)
Process managerSupervisor (production)
PAYMENT_WEBHOOK_SECRET must be set before booting the application. PaymentWebhookController reads this value at boot time, and several Artisan commands (including migrate and queue:listen) will throw if it is empty or missing from .env.

​
Step 1: Install dependencies

composer install
npm install

​
Step 2: Create and configure .env

cp .env.example .env
Then set your values. See Environment variables below for descriptions of every key.

​
Step 3: Generate the application key

php artisan key:generate

​
Step 4: Set up the database

SQLite requires no server. It is suitable for local development and quick demos.
macOS / Linux
touch database/database.sqlite
PowerShell
New-Item database/database.sqlite -ItemType File -Force
Set the following in .env:
.env
DB_CONNECTION=sqlite
Leave the DB_HOST, DB_PORT, DB_DATABASE, DB_USERNAME, and DB_PASSWORD lines commented out.

​
Step 5: Run migrations

php artisan migrate --seed
The --seed flag populates demo data: categories, cities, tenants, products, and two user accounts (super admin and a tenant owner). See database/seeders/DatabaseSeeder.php for the full list of seeded records.
Review database/seeders/DatabaseSeeder.php before running the seeder in any shared or non-local environment. It creates known credentials and publicly accessible demo tenants.
php artisan storage:link
This creates a symbolic link from public/storage to storage/app/public, which is required for serving locally uploaded media.

​
Environment variables

​
Application

VariableDescriptionExample
APP_NAMEDisplay name shown in emails and UIVito Business OS
APP_ENVEnvironment (local, production)local
APP_KEYEncryption key — generated by key:generate—
APP_DEBUGShow detailed errors (true in local only)false
APP_URLFull base URL including protocolhttp://localhost:8000
APP_DOMAINRoot domain used for cookies and tenancylocalhost

​
Database

VariableDescription
DB_CONNECTIONDriver: sqlite or mysql
DB_HOSTDatabase host (MySQL only)
DB_PORTDatabase port (MySQL only, default 3306)
DB_DATABASEDatabase name or path to SQLite file
DB_USERNAMEDatabase user (MySQL only)
DB_PASSWORDDatabase password (MySQL only)

​
Session, cache, and queue

VariableSQLite / local valueRedis / production value
SESSION_DRIVERdatabaseredis
CACHE_STOREdatabaseredis
QUEUE_CONNECTIONdatabaseredis
.env (Redis)
REDIS_CLIENT=phpredis
REDIS_HOST=127.0.0.1
REDIS_PASSWORD=null
REDIS_PORT=6379

​
Storage and S3

By default, files are stored locally at storage/app/public. To switch to S3:
.env
FILESYSTEM_DISK=s3
AWS_ACCESS_KEY_ID=your_key_id
AWS_SECRET_ACCESS_KEY=your_secret
AWS_DEFAULT_REGION=us-east-1
AWS_BUCKET=your-bucket-name
AWS_USE_PATH_STYLE_ENDPOINT=false
The infrastructure/aws/ directory contains a lifecycle policy you can apply to your S3 bucket for automatic orphan cleanup.

​
Broadcasting and WebSockets (Reverb)

Vito Business OS uses Laravel Reverb for real-time broadcasting.
.env
BROADCAST_CONNECTION=reverb
REVERB_APP_ID=your_app_id
REVERB_APP_KEY=your_app_key
REVERB_APP_SECRET=your_app_secret
REVERB_HOST=localhost
REVERB_PORT=8080
REVERB_SCHEME=http

VITE_REVERB_APP_KEY="${REVERB_APP_KEY}"
VITE_REVERB_HOST="${REVERB_HOST}"
VITE_REVERB_PORT="${REVERB_PORT}"
VITE_REVERB_SCHEME="${REVERB_SCHEME}"
For development you can leave BROADCAST_CONNECTION at its default value. Real-time features (order updates, low stock alerts, login alerts) require Reverb to be running.

​
Payments

VariableDescription
PAYMENT_PROVIDERPayment adapter: generic (local/demo) or stripe
PAYMENT_WEBHOOK_SECRETSecret used to verify incoming webhook signatures. Required at boot.
.env
PAYMENT_PROVIDER=generic
PAYMENT_WEBHOOK_SECRET=local-secret

​
Web Push (VAPID)

Optional. Required only if you want browser push notifications.
.env
VAPID_SUBJECT=mailto:[email protected]
VAPID_PUBLIC_KEY=
VAPID_PRIVATE_KEY=
Generate VAPID keys with: 
php artisan webpush:vapid

​
Starting the development environment

composer run dev
This uses concurrently to run four processes in one terminal session:
ProcessCommand
HTTP serverphp artisan serve
Queue listenerphp artisan queue:listen --tries=1
Log viewerphp artisan pail --timeout=0
Vite dev servernpm run dev
To run a production build of frontend assets instead: 
npm run build

​
Production setup with Supervisor

For production, use Supervisor to keep the queue worker and Reverb process running. 
# Copy the provided Supervisor config
sudo cp devops/conecta-worker.conf /etc/supervisor/conf.d/
sudo supervisorctl reread
sudo supervisorctl update
sudo supervisorctl start conecta:*
The devops/ directory also contains:
FilePurpose
deploy.shZero-downtime atomic deployment script
nginx_app.confNginx server block with security hardening
conecta-worker.confSupervisor config for queue workers and Reverb
See devops/README.md for the complete server provisioning walkthrough.
The Supervisor config in devops/conecta-worker.conf also manages the Reverb WebSocket server process. You do not need a separate daemon configuration for Reverb.

​
Verifying your installation

After setup, open the following URLs to confirm everything is working:
URLExpected
http://localhost:8000Public landing page
http://localhost:8000/adminFilament super admin login
http://localhost:8000/appFilament tenant panel login
http://localhost:8000/api/documentationSwagger UI for REST API v1

​
Next steps

Architecture overview

Understand the modular monolith, DDD layers, and bounded contexts.

Multi-tenancy

Learn how tenant routing, isolation, and panels are structured.

Deployment

Full production deployment guide with Nginx and zero-downtime deploys.

API reference

Explore the REST API v1, authentication, and webhook contracts.

Build docs developers (and LLMs) love

Get started for freeTalk to us