Skip to main content

​
Prerequisites

Before installing OptiFlow, ensure you have the following software installed:

PHP 8.3 or higher

OptiFlow requires PHP 8.3+ with common extensions

Node.js 20 or higher

For building frontend assets with Vite

Composer

PHP dependency manager

Laravel Herd (Recommended)

Or any local development environment (Valet, Homestead, Docker)

​
Required PHP Extensions

Ensure the following PHP extensions are enabled:
  • ext-zip - For handling file archives
  • ext-pdo - For database connections
  • ext-mbstring - For string manipulation
  • ext-xml - For XML processing
  • ext-curl - For HTTP requests
  • ext-gd or ext-imagick - For image processing
If using Laravel Herd, all required PHP extensions are pre-configured.

​
Installation Steps

1

Clone the Repository

Clone the OptiFlow repository to your local machine:
git clone https://github.com/luisscruza/optiflow.git
cd optiflow
For production deployments, clone a specific release tag instead of the main branch for stability.
2

Install PHP Dependencies

Install the required PHP packages using Composer:
composer install
This will install:
  • Laravel 12 framework
  • Laravel Tenancy for multi-tenancy
  • Filament for admin panel
  • Inertia.js Laravel adapter
  • Spatie packages (permissions, activity log, media library)
  • DomPDF for PDF generation
  • And other dependencies
For production, use composer install --optimize-autoloader --no-dev to exclude development dependencies.
3

Install JavaScript Dependencies

Install the required Node.js packages:
npm install
This will install:
  • React 19
  • Inertia.js React adapter
  • TypeScript
  • Tailwind CSS 4
  • Vite and Laravel Vite plugin
  • Radix UI components
  • And other frontend dependencies
4

Configure Environment

Copy the example environment file and generate an application key:
cp .env.example .env
php artisan key:generate
Edit the .env file to configure your environment:
.env
APP_NAME=OptiFlow
APP_ENV=local
APP_DEBUG=true
APP_URL=http://optiflow.test

# Database Configuration (SQLite for development)
DB_CONNECTION=sqlite

# For MySQL/PostgreSQL in production:
# DB_CONNECTION=mysql
# DB_HOST=127.0.0.1
# DB_PORT=3306
# DB_DATABASE=optiflow
# DB_USERNAME=root
# DB_PASSWORD=

# Session & Cache
SESSION_DRIVER=database
CACHE_STORE=database
QUEUE_CONNECTION=database

# Mail Configuration (use 'log' for development)
MAIL_MAILER=log
Never commit your .env file to version control. It contains sensitive credentials.
5

Create SQLite Database

If using SQLite (default for development), create the database file:
touch database/database.sqlite
For MySQL or PostgreSQL, create the database using your database management tool.
6

Run Database Migrations

Create all required database tables:
php artisan migrate
This will create:
  • Central application tables (users, tenants, domains)
  • Permission tables (roles, permissions)
  • Cache and session tables
Tenant-specific tables are created automatically when you create a new tenant.
7

Build Frontend Assets

Compile the React frontend:
npm run build
For development with hot module replacement:
npm run dev
During development, use composer run dev to start both the Laravel server and Vite dev server concurrently.
8

Access the Application

If using Laravel Herd, your application is automatically available at:
  • Central Admin: https://optiflow.test/admin
  • Tenant Portal: https://{tenant}.optiflow.test
For other environments, start the development server:
php artisan serve
Or use the development script that starts everything:
composer run dev
This runs concurrently:
  • Laravel development server (php artisan serve)
  • Queue worker (php artisan queue:listen)
  • Log viewer (php artisan pail)
  • Vite dev server (npm run dev)

​
Optional: DGII Data Sync

If you’re operating in the Dominican Republic and need to sync RNC (tax ID) data from DGII: 
php artisan sync:dgii
This command downloads and imports the official RNC database from DGII for contact validation and autofill.
This command may take several minutes to complete as it downloads and processes a large dataset.

​
Production Deployment

For production deployments, follow these additional steps:

​
Environment Configuration

Update your .env file for production:
.env
APP_ENV=production
APP_DEBUG=false
APP_URL=https://yourdomain.com

# Use a strong database password
DB_CONNECTION=mysql
DB_HOST=your-database-host
DB_DATABASE=optiflow_production
DB_USERNAME=optiflow_user
DB_PASSWORD=strong-random-password

# Configure your mail provider
MAIL_MAILER=smtp
MAIL_HOST=smtp.example.com
MAIL_PORT=587
MAIL_USERNAME=[email protected]
MAIL_PASSWORD=your-email-password
MAIL_ENCRYPTION=tls

# Use Redis for better performance
CACHE_STORE=redis
SESSION_DRIVER=redis
QUEUE_CONNECTION=redis

# Configure AWS S3 for file storage (recommended)
FILESYSTEM_DISK=s3
AWS_ACCESS_KEY_ID=your-key-id
AWS_SECRET_ACCESS_KEY=your-secret-key
AWS_DEFAULT_REGION=us-east-1
AWS_BUCKET=your-bucket-name

​
Optimization Commands

# Optimize configuration loading
php artisan config:cache

# Optimize route loading
php artisan route:cache

# Optimize view compilation
php artisan view:cache

# Optimize event loading
php artisan event:cache

# Build production assets
npm run build

​
Queue Worker

Set up a queue worker as a system service to process background jobs: 
php artisan queue:work --tries=3 --timeout=90
Use a process monitor like Supervisor to keep the queue worker running in production.

​
Task Scheduler

Add this to your crontab to run Laravel’s task scheduler: 
* * * * * cd /path-to-optiflow && php artisan schedule:run >> /dev/null 2>&1

​
Development Tools

OptiFlow includes several development tools:

​
Code Quality

# Format code with Laravel Pint
composer run lint

# Run static analysis with PHPStan
composer run test:types

# Refactor code with Rector
composer run refactor

​
Testing

# Run all tests
composer run test

# Run only unit tests
composer run test:unit

# Run with coverage
php artisan test --coverage

​
Troubleshooting

​
Permission Errors

If you encounter permission errors, ensure proper ownership: 
# Set proper permissions for storage and cache
chmod -R 775 storage bootstrap/cache
chown -R www-data:www-data storage bootstrap/cache

​
Database Connection Issues

Verify your database credentials in .env and ensure the database server is running: 
# Test database connection
php artisan migrate:status

​
Asset Build Failures

Clear the Node.js cache and reinstall dependencies: 
rm -rf node_modules package-lock.json
npm cache clean --force
npm install
npm run build

​
Tenant Subdomain Not Working

If using Laravel Herd, ensure your .test domain is properly configured. For other environments, configure your web server (nginx/Apache) to support wildcard subdomains: 
server_name optiflow.test *.optiflow.test;
Laravel Herd automatically handles subdomain routing for .test domains. No additional configuration is needed. Just ensure your APP_URL in .env matches your Herd domain.

​
Next Steps

Now that OptiFlow is installed, proceed to the Quickstart Guide to:
  • Create your first tenant
  • Set up your first workspace
  • Create users and assign roles
  • Start using OptiFlow’s features

Quickstart Guide

Get started with OptiFlow in minutes

Configuration Guide

Learn about multi-tenancy and workspace setup

API Documentation

Integrate OptiFlow with other systems

User Guides

Learn how to use OptiFlow’s features

Build docs developers (and LLMs) love

Get started for freeTalk to us