Skip to main content

​
Overview

Filebright uses a dual-database architecture:
  • PostgreSQL: Stores application data (users, document metadata, sessions, jobs)
  • MongoDB: Stores document chunks with vector embeddings for semantic search
This architecture separates structured application data from unstructured vector data, optimizing performance for both traditional queries and AI-powered search.

​
PostgreSQL

PostgreSQL serves as the primary relational database for structured application data.

​
What’s stored in PostgreSQL

  • User accounts and authentication data
  • Document metadata (filename, size, status, upload date)
  • Session data
  • Queue jobs for background processing
  • Cache entries

​
Connection configuration

Configure PostgreSQL using these environment variables: 
DB_CONNECTION=pgsql
DB_HOST=db
DB_PORT=5432
DB_DATABASE=filebright
DB_USERNAME=user
DB_PASSWORD=secret

​
Docker setup

The included docker-compose.yml automatically sets up PostgreSQL:
docker-compose.yml
db:
  image: postgres:alpine
  container_name: filebright_db
  restart: unless-stopped
  environment:
    POSTGRES_DB: ${DB_DATABASE:-filebright}
    POSTGRES_USER: ${DB_USERNAME:-user}
    POSTGRES_PASSWORD: ${DB_PASSWORD:-secret}
  ports:
    - "5432:5432"
  volumes:
    - filebright_db_data:/var/lib/postgresql/data
  healthcheck:
    test: ["CMD-SHELL", "pg_isready -U ${DB_USERNAME:-user} -d ${DB_DATABASE:-filebright}"]
    interval: 10s
    timeout: 5s
    retries: 5

​
Manual PostgreSQL installation

If you’re not using Docker, install PostgreSQL manually: 
sudo apt update
sudo apt install postgresql postgresql-contrib
sudo systemctl start postgresql
sudo systemctl enable postgresql

brew install postgresql@15
brew services start postgresql@15
Download and install from postgresql.org

​
Create database and user

Create a dedicated database and user for Filebright: 
psql -U postgres

CREATE DATABASE filebright;
CREATE USER filebright_user WITH PASSWORD 'your_password';
GRANT ALL PRIVILEGES ON DATABASE filebright TO filebright_user;
\q

​
Run migrations

Once PostgreSQL is configured, run the migrations to create the database schema: 
php artisan migrate
This creates the following tables:
  • users - User accounts
  • document_metadata - Document information and status
  • sessions - User sessions
  • jobs - Background job queue
  • cache - Application cache
The document_metadata table includes a vector_id field that references document chunks stored in MongoDB.

​
MongoDB

MongoDB stores document chunks and their vector embeddings for efficient semantic search.

​
What’s stored in MongoDB

  • Document text chunks (split from uploaded documents)
  • Vector embeddings for each chunk (generated by OpenRouter)
  • Metadata for filtering (user ID, document ID, chunk index)

​
Connection configuration

Configure MongoDB using these environment variables: 
MONGODB_URI=mongodb://mongodb:27017
MONGODB_DATABASE=filebright

​
Manual MongoDB installation

wget -qO - https://www.mongodb.org/static/pgp/server-7.0.asc | sudo apt-key add -
echo "deb [ arch=amd64,arm64 ] https://repo.mongodb.org/apt/ubuntu jammy/mongodb-org/7.0 multiverse" | sudo tee /etc/apt/sources.list.d/mongodb-org-7.0.list
sudo apt update
sudo apt install -y mongodb-org
sudo systemctl start mongod
sudo systemctl enable mongod

brew tap mongodb/brew
brew install [email protected]
brew services start [email protected]
Download and install from mongodb.com
For production deployments, we recommend using MongoDB Atlas:
  1. Create a free account at mongodb.com/cloud/atlas
  2. Create a new cluster
  3. Create a database user
  4. Whitelist your application’s IP address
  5. Get your connection string and add it to .env
MongoDB Atlas requires creating a vector search index for the embeddings to work. See the Vector Search Index section below.

​
Vector search index

For semantic search to work, you must create a vector search index in MongoDB.

​
Using MongoDB Atlas UI

  1. Navigate to your cluster in MongoDB Atlas
  2. Click Search in the left sidebar
  3. Click Create Search Index
  4. Select JSON Editor
  5. Use the following configuration:
{
  "mappings": {
    "dynamic": true,
    "fields": {
      "embedding": {
        "type": "knnVector",
        "dimensions": 1536,
        "similarity": "cosine"
      },
      "metadata": {
        "type": "document",
        "fields": {
          "user_id": {
            "type": "number"
          }
        }
      }
    }
  }
}
  1. Name the index vector_index
  2. Select the document_chunks collection
  3. Click Create Search Index
The dimensions value (1536) matches the text-embedding-3-small model. If you use a different embedding model, adjust this value accordingly.

​
Using MongoDB Shell

Connect to your MongoDB instance and run: 
use filebright

db.document_chunks.createSearchIndex(
  "vector_index",
  {
    "type": "vectorSearch",
    "fields": [
      {
        "type": "vector",
        "path": "embedding",
        "numDimensions": 1536,
        "similarity": "cosine"
      },
      {
        "type": "filter",
        "path": "metadata.user_id"
      }
    ]
  }
)

​
Document chunk schema

Each document stored in MongoDB follows this structure: 
{
  "_id": ObjectId("..."),
  "document_id": 123,
  "content": "This is a chunk of text from the document...",
  "embedding": [0.123, -0.456, 0.789, ...],  // 1536 dimensions
  "metadata": {
    "user_id": 1,
    "chunk_index": 0
  },
  "created_at": ISODate("2026-03-03T00:00:00Z"),
  "updated_at": ISODate("2026-03-03T00:00:00Z")
}

​
PHP MongoDB extension

Filebright requires the MongoDB PHP extension. It’s automatically installed in the Docker container, but for local development: 
sudo pecl install mongodb
echo "extension=mongodb.so" | sudo tee /etc/php/8.2/mods-available/mongodb.ini
sudo phpenmod mongodb
sudo systemctl restart php8.2-fpm

pecl install mongodb
echo "extension=mongodb.so" >> $(php --ini | grep "Loaded Configuration File" | awk '{print $4}')
Download the DLL from pecl.php.net and add to php.ini:
extension=php_mongodb.dll
Verify installation: 
php -m | grep mongodb

​
Connection testing

Test your database connections:

​
PostgreSQL

php artisan tinker

DB::connection('pgsql')->getPdo();
// Should return PDO instance without errors

​
MongoDB

php artisan tinker

DB::connection('mongodb')->getMongoDB();
// Should return MongoDB\Database instance without errors

​
Troubleshooting

  • Check if PostgreSQL is running: sudo systemctl status postgresql
  • Verify host and port in .env
  • Check firewall rules
  • For Docker: ensure db service is healthy
  • Verify connection string format
  • Check username and password
  • Ensure database user has proper permissions
  • For Atlas: verify IP whitelist
  • Verify vector_index exists in MongoDB
  • Check index name matches code (vector_index)
  • Ensure embedding dimensions match (1536 for text-embedding-3-small)
  • Wait a few minutes for index to become active after creation
  • Install the MongoDB PHP extension: pecl install mongodb
  • Enable the extension in php.ini
  • Restart PHP-FPM or web server
  • Verify: php -m | grep mongodb

​
Next steps

AI integration

Configure OpenRouter for embeddings and chat

Docker deployment

Deploy Filebright with Docker

Build docs developers (and LLMs) love

Get started for freeTalk to us