Installation

Prerequisites

Before installing Filebright, ensure you have the following installed on your system:

Required software

PHP 8.2+

Required for Laravel 12. Check with php -v

Composer

PHP dependency manager. Install from getcomposer.org

Node.js 18+

Required for Vue 3 and Vite. Check with node -v

npm or yarn

Node package manager. Included with Node.js

Database requirements

SQLite (Development)
PostgreSQL (Production)
MongoDB (Vector Storage)

SQLite is pre-configured for development and requires no setup:

# SQLite extension is typically bundled with PHP
php -m | grep sqlite

SQLite is perfect for local development but consider PostgreSQL for production workloads.

For production environments, PostgreSQL is recommended:

Ubuntu/Debian

sudo apt update
sudo apt install postgresql postgresql-contrib
sudo systemctl start postgresql

macOS (Homebrew)

brew install postgresql@15
brew services start postgresql@15

Create the database:

sudo -u postgres psql
CREATE DATABASE filebright;
CREATE USER filebright_user WITH PASSWORD 'your_password';
GRANT ALL PRIVILEGES ON DATABASE filebright TO filebright_user;
\q

MongoDB is required for vector storage and similarity search:

Ubuntu/Debian

# Import MongoDB public GPG key
curl -fsSL https://www.mongodb.org/static/pgp/server-7.0.asc | \
  sudo gpg -o /usr/share/keyrings/mongodb-server-7.0.gpg --dearmor

# Add MongoDB repository
echo "deb [ signed-by=/usr/share/keyrings/mongodb-server-7.0.gpg ] https://repo.mongodb.org/apt/ubuntu jammy/mongodb-org/7.0 multiverse" | \
  sudo tee /etc/apt/sources.list.d/mongodb-org-7.0.list

# Install MongoDB
sudo apt update
sudo apt install -y mongodb-org

# Start MongoDB
sudo systemctl start mongod
sudo systemctl enable mongod

macOS (Homebrew)

brew tap mongodb/brew
brew install [email protected]
brew services start [email protected]

MongoDB is essential for Filebright’s RAG functionality. The application uses MongoDB’s $vectorSearch for similarity matching.

After installation, create the vector index:

mongosh
use filebright
db.document_chunks.createIndex(
  { "embedding": "vector" },
  {
    "name": "vector_index",
    "vectorSearchOptions": {
      "type": "knnVector",
      "numDimensions": 1536,
      "similarity": "cosine"
    }
  }
)

API credentials

Filebright requires an OpenRouter API key for AI functionality:

Sign up at openrouter.ai
Generate an API key from your dashboard
Add credits to your account (embeddings and chat have usage costs)

OpenRouter provides access to multiple AI models through a single API. Filebright uses it for both text embeddings and chat completions.

Installation steps

Clone the repository

Clone Filebright to your local machine or server:

git clone https://github.com/your-org/filebright.git
cd filebright

Install backend dependencies

Navigate to the backend directory and install PHP dependencies:

cd backend
composer install

This installs all required packages including:

Laravel Framework 12
Laravel Sanctum for authentication
MongoDB Laravel driver
PDF parser library

The key dependencies from composer.json:

composer.json

{
  "require": {
    "php": "^8.2",
    "laravel/framework": "^12.0",
    "laravel/sanctum": "^4.0",
    "mongodb/laravel-mongodb": "^5.6",
    "smalot/pdfparser": "^2.12"
  }
}

Install frontend dependencies

Navigate to the frontend directory and install Node packages:

cd ../frontend
npm install

This installs:

Vue 3 and Vue Router
Vite for fast builds
PrimeVue component library
Lucide icons

From package.json:

package.json

{
  "dependencies": {
    "vue": "^3.5.25",
    "vue-router": "^4.6.4",
    "primevue": "^4.5.4",
    "lucide-vue-next": "^0.575.0"
  }
}

Configure environment

Copy the example environment file and generate an application key:

cd ../backend
cp .env.example .env
php artisan key:generate

Edit .env with your configuration:

APP_NAME=Filebright
APP_ENV=local
APP_DEBUG=true
APP_URL=http://localhost:8000

# SQLite Database
DB_CONNECTION=sqlite

# MongoDB Vector Storage
MONGODB_URI=mongodb://localhost:27017
MONGODB_DATABASE=filebright

# OpenRouter AI Services
OPENROUTER_API_KEY=sk-or-v1-your-api-key-here
OPENROUTER_EMBEDDING_MODEL=text-embedding-3-small
OPENROUTER_CHAT_MODEL=openai/gpt-3.5-turbo

# Queue & Cache
QUEUE_CONNECTION=database
CACHE_STORE=database

# Session
SESSION_DRIVER=database
SESSION_LIFETIME=120

For production, consider using Redis for queue and cache instead of database for better performance.

Run database migrations

Create the database schema:

# For SQLite, create the database file first
touch database/database.sqlite

# Run migrations
php artisan migrate

This creates tables for:

users - User accounts
document_metadata - Document information
sessions - User sessions
jobs and failed_jobs - Queue management
personal_access_tokens - API tokens (Sanctum)

MongoDB collections (document_chunks) are created automatically when documents are processed.

Build frontend assets

Development
Production

For development with hot reload:

cd frontend
npm run dev

This starts the Vite dev server on http://localhost:80 with HMR (Hot Module Replacement).

For production, build optimized assets:

cd frontend
npm run build

This creates optimized bundles in frontend/dist/.

Start the application

Development (Composer)
Development (Manual)
Production

The easiest way to run all services in development:

cd backend
composer run dev

This single command starts:

Laravel development server (php artisan serve) on port 8000
Queue worker (php artisan queue:work) for background jobs
Log viewer (php artisan pail) for real-time logs
Vite dev server (npm run dev) on port 80

From composer.json:

composer.json

{
  "scripts": {
    "dev": [
      "Composer\\Config::disableProcessTimeout",
      "npx concurrently -c \"#93c5fd,#c4b5fd,#fb7185,#fdba74\" \"php artisan serve\" \"php artisan queue:listen --tries=1 --timeout=0\" \"php artisan pail --timeout=0\" \"npm run dev\" --names=server,queue,logs,vite --kill-others"
    ]
  }
}

The concurrently package provides colored output for each service, making it easy to monitor all processes at once.

Or start each service in separate terminals:

Terminal 1: Laravel Server

cd backend
php artisan serve

Terminal 2: Queue Worker

cd backend
php artisan queue:work --tries=3

Terminal 3: Frontend

cd frontend
npm run dev

For production, use a process manager like Supervisor for queue workers:

/etc/supervisor/conf.d/filebright-worker.conf

[program:filebright-worker]
process_name=%(program_name)s_%(process_num)02d
command=php /var/www/filebright/backend/artisan queue:work --sleep=3 --tries=3 --max-time=3600
autostart=true
autorestart=true
stopasgroup=true
killasgroup=true
user=www-data
numprocs=2
redirect_stderr=true
stdout_logfile=/var/www/filebright/backend/storage/logs/worker.log
stopwaitsecs=3600

Serve the application with Nginx:

/etc/nginx/sites-available/filebright

server {
    listen 80;
    server_name filebright.yourdomain.com;
    root /var/www/filebright/backend/public;

    add_header X-Frame-Options "SAMEORIGIN";
    add_header X-Content-Type-Options "nosniff";

    index index.php;

    charset utf-8;

    location / {
        try_files $uri $uri/ /index.php?$query_string;
    }

    location = /favicon.ico { access_log off; log_not_found off; }
    location = /robots.txt  { access_log off; log_not_found off; }

    error_page 404 /index.php;

    location ~ \.php$ {
        fastcgi_pass unix:/var/run/php/php8.2-fpm.sock;
        fastcgi_param SCRIPT_FILENAME $realpath_root$fastcgi_script_name;
        include fastcgi_params;
    }

    location ~ /\.(?!well-known).* {
        deny all;
    }
}

Docker setup

Filebright includes Docker Compose configuration for easy deployment:

docker-compose.yml

version: "3.8"

services:
  app:
    build:
      context: ./backend
      dockerfile: Dockerfile
    container_name: filebright_app
    restart: unless-stopped
    working_dir: /var/www
    env_file: ./backend/.env
    depends_on:
      db:
        condition: service_healthy

  web:
    image: nginx:alpine
    container_name: filebright_web
    restart: unless-stopped
    ports:
      - "8000:80"
    volumes:
      - ./backend/public:/var/www/public

  worker:
    build:
      context: ./backend
      dockerfile: Dockerfile
    container_name: filebright_worker
    restart: unless-stopped
    command: ["php", "artisan", "queue:work"]

  db:
    image: postgres:alpine
    container_name: filebright_db
    restart: unless-stopped
    environment:
      POSTGRES_DB: filebright
      POSTGRES_USER: user
      POSTGRES_PASSWORD: secret
    ports:
      - "5432:5432"

  frontend:
    build:
      context: ./frontend
      dockerfile: Dockerfile
    container_name: filebright_frontend
    restart: unless-stopped
    ports:
      - "80:80"

Start with Docker:

# Build and start all services
docker-compose up -d

# Run migrations
docker-compose exec app php artisan migrate

# View logs
docker-compose logs -f

The Docker setup includes PostgreSQL but you still need to configure MongoDB separately. Update MONGODB_URI in your .env to point to your MongoDB instance.

Verification

After installation, verify everything is working:

Check API

Visit http://localhost:8000/api/user (should return 401 - authentication required)

Check Frontend

Visit http://localhost:80 (should show the login/register page)

Check Queue

Ensure the queue worker is running:

php artisan queue:work --once

Check MongoDB

Verify MongoDB connection:

mongosh
use filebright
show collections

Troubleshooting

MongoDB connection failed

Ensure MongoDB is running:

sudo systemctl status mongod

Check the MONGODB_URI in your .env file. For local MongoDB:

MONGODB_URI=mongodb://127.0.0.1:27017

Queue jobs not processing

Make sure the queue worker is running:

php artisan queue:work

Check failed jobs:

php artisan queue:failed

Retry failed jobs:

php artisan queue:retry all

OpenRouter API errors

Verify your API key is correct and has credits:

curl https://openrouter.ai/api/v1/auth/key \
  -H "Authorization: Bearer YOUR_API_KEY"

Check the logs for specific error messages:

tail -f backend/storage/logs/laravel.log

File upload errors

Ensure the storage directory is writable:

chmod -R 775 backend/storage
chown -R www-data:www-data backend/storage

Check PHP upload limits in php.ini:

upload_max_filesize = 100M
post_max_size = 100M
max_execution_time = 300

Next steps

Quick start guide

Upload your first document and start chatting

Configuration

Customize AI models, vector search, and more

API reference

Explore all available API endpoints

Architecture

Learn how Filebright processes documents

Get Started

Features

Configuration

Deployment

Prerequisites

Required software

PHP 8.2+

Composer

Node.js 18+

npm or yarn

Database requirements

API credentials

Installation steps

Docker setup

Verification

Troubleshooting

Next steps

Quick start guide

Configuration

API reference

Architecture

Build docs developers (and LLMs) love

Get Started

Features

Configuration

Deployment

​Prerequisites

​Required software

PHP 8.2+

Composer

Node.js 18+

npm or yarn

​Database requirements

​API credentials

​Installation steps

​Docker setup

​Verification

​Troubleshooting

​Next steps

Quick start guide

Configuration

API reference

Architecture

Build docs developers (and LLMs) love

Prerequisites

Required software

Database requirements

API credentials

Installation steps

Docker setup

Verification

Troubleshooting

Next steps