Deploy PatoLab to Production — Server and Docker Guide

Deploying PatoLab to production requires a few critical steps beyond a standard Laravel application: Chromium must be available on the host for PDF invoice generation, the Wayfinder TypeScript helpers must be generated before the Vite build, and the priorities_specimens_order table must be kept clean after any database restore to prevent Kanban board duplication. This guide covers both a traditional server deployment and a containerised Docker deployment.

Traditional Server
Docker

Set production environment values

Create or update the .env file on the server. At a minimum, set the following production-critical values:

.env

APP_ENV=production
APP_DEBUG=false
APP_URL=https://your-domain.com

Also configure your production database connection and any other service credentials (WhatsApp, mail, etc.):

.env

DB_CONNECTION=mysql
DB_HOST=127.0.0.1
DB_PORT=3306
DB_DATABASE=patolab_production
DB_USERNAME=patolab_user
DB_PASSWORD=strong_secret_password

QUEUE_CONNECTION=database
SESSION_DRIVER=database
CACHE_STORE=database

Install Composer dependencies (optimised)

Install PHP packages with development dependencies excluded and the autoloader fully optimised:

composer install --no-dev --optimize-autoloader

Build frontend assets

Install exact npm dependency versions from the lockfile and compile the production Vite bundle:

npm ci && npm run build

The compiled assets are written to public/build/ and referenced by Laravel’s Vite blade helper.

Cache Laravel configuration, routes, and views

Dramatically improve response times by caching the three most frequently loaded framework artefacts:

php artisan config:cache && php artisan route:cache && php artisan view:cache

Important: After running config:cache, changes to your .env file will not be reflected until you re-run php artisan config:cache. Always re-run all three cache commands after any deployment.

Set storage permissions

Ensure the storage and bootstrap/cache directories are writable by the web server user (typically www-data for Nginx/Apache with PHP-FPM):

chmod -R 775 storage
chmod -R 775 bootstrap/cache
chown -R www-data:www-data storage bootstrap/cache

# Ensure all directories under storage are traversable (775)
sudo find storage -type d -exec chmod 775 {} \;

# Ensure all files under storage are readable (664)
sudo find storage -type f -exec chmod 664 {} \;

Run production migrations

Apply any pending database migrations using the --force flag to skip the interactive production confirmation:

php artisan migrate --force

Start the queue worker

PatoLab uses the database queue for invoice PDF generation, WhatsApp notifications, and other background jobs. Start a persistent daemon worker:

php artisan queue:work --daemon

For production it is strongly recommended to manage this process with Supervisor or systemd so it is restarted automatically if it exits. Below is a minimal Supervisor configuration example:

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

[program:patolab-worker]
command=php /var/www/patolab/artisan queue:work --daemon
directory=/var/www/patolab
user=www-data
autostart=true
autorestart=true
stdout_logfile=/var/log/supervisor/patolab-worker.log
stderr_logfile=/var/log/supervisor/patolab-worker-error.log

Configure Chromium for PDF generation

PatoLab uses Spatie Browsershot (backed by Chromium) to render PDF invoices and reports. Ensure Chromium is installed on the server, then set the executable path in your .env:

.env

PUPPETEER_EXECUTABLE_PATH=/usr/bin/chromium

Adjust the path to match your Chromium installation (e.g. /usr/bin/google-chrome-stable on Ubuntu with the Google Chrome package). The BROWSERSHOT_INCLUDE_PATH, BROWSERSHOT_NODE_BINARY, and BROWSERSHOT_NPM_BINARY variables in .env.example can also be set if Browsershot cannot locate Node.js automatically:

.env

BROWSERSHOT_INCLUDE_PATH='$PATH:/usr/local/bin:/usr/bin'
BROWSERSHOT_NODE_BINARY='/usr/local/bin/node'
BROWSERSHOT_NPM_BINARY='/usr/local/bin/npm'
BROWSERSHOT_CHROME_PATH='/usr/bin/google-chrome-stable'

PatoLab ships with a production-ready dockerfile in the project root. The image is based on php:8.3-fpm and bundles Nginx, Supervisor, PHP-FPM, Node.js, npm, and Chromium into a single container for straightforward deployment.What the Dockerfile does:

Installs all required PHP extensions (pdo, pdo_mysql, mbstring, bcmath, gd, zip, opcache)
Installs Composer, Node.js, npm, and Chromium via apt
Runs composer install --no-dev --optimize-autoloader and npm ci using layer caching
Generates Wayfinder TypeScript helpers (php artisan wayfinder:generate --with-form)
Compiles frontend assets (npm run build)
Sets PUPPETEER_EXECUTABLE_PATH=/usr/bin/chromium automatically
Runs Nginx (port 8080) and PHP-FPM under Supervisor

Building the image

docker build -t patolab:latest .

Running the container

Pass your production environment variables at runtime. At minimum you must supply the application key and database credentials:

docker run -d \
  --name patolab \
  -p 8080:8080 \
  -e APP_ENV=production \
  -e APP_DEBUG=false \
  -e APP_KEY=base64:YOUR_GENERATED_KEY_HERE \
  -e APP_URL=https://your-domain.com \
  -e DB_CONNECTION=mysql \
  -e DB_HOST=your-db-host \
  -e DB_PORT=3306 \
  -e DB_DATABASE=patolab_production \
  -e DB_USERNAME=patolab_user \
  -e DB_PASSWORD=strong_secret_password \
  -e QUEUE_CONNECTION=database \
  -e PUPPETEER_EXECUTABLE_PATH=/usr/bin/chromium \
  patolab:latest

Docker Compose example

PatoLab does not ship a docker-compose.yml file. The sample below is a starting point you create yourself in the project root, giving you a complete setup with a MySQL service and a persistent volume for storage:

docker-compose.yml (create this file yourself)

services:
  app:
    build: .
    ports:
      - "8080:8080"
    environment:
      APP_ENV: production
      APP_DEBUG: "false"
      APP_KEY: base64:YOUR_GENERATED_KEY_HERE
      APP_URL: https://your-domain.com
      DB_CONNECTION: mysql
      DB_HOST: db
      DB_PORT: 3306
      DB_DATABASE: patolab
      DB_USERNAME: patolab
      DB_PASSWORD: secret
      QUEUE_CONNECTION: database
      PUPPETEER_EXECUTABLE_PATH: /usr/bin/chromium
    volumes:
      - storage_data:/app/storage
    depends_on:
      - db

  db:
    image: mysql:8.0
    environment:
      MYSQL_DATABASE: patolab
      MYSQL_USER: patolab
      MYSQL_PASSWORD: secret
      MYSQL_ROOT_PASSWORD: root_secret
    volumes:
      - db_data:/var/lib/mysql

volumes:
  storage_data:
  db_data:

After the container starts, run migrations inside the container:

docker exec -it patolab php artisan migrate --force

Database Restoration Warning

When restoring a database backup or copying data into a new database instance, the priorities_specimens_order table may contain stale or mismatched records. This will cause specimen cards to appear duplicated on the Kanban board.After every database restoration, run the following cleanup SQL to remove obsolete rows:

DELETE FROM priorities_specimens_order
WHERE NOT EXISTS (
    SELECT 1 FROM specimen
    WHERE specimen.id = priorities_specimens_order.specimen_id
      AND specimen.priority_id = priorities_specimens_order.priority_id
);

Alternatively, run it via Laravel Tinker without needing a direct database connection:

php artisan tinker --execute="DB::table('priorities_specimens_order')->whereNotExists(function(\$q) { \$q->select(DB::raw(1))->from('specimen')->whereColumn('specimen.id', '=', 'priorities_specimens_order.specimen_id')->whereColumn('specimen.priority_id', '=', 'priorities_specimens_order.priority_id'); })->delete();"

Server Requirements

The following server-level dependencies are required to run PatoLab in production:

PHP

Requirement	Minimum Version
PHP	8.3+
Extension: `gd`	Required for image processing
Extension: `pdo_mysql`	Required for MySQL database connections
Extension: `mbstring`	Required by Laravel framework
Extension: `bcmath`	Required by Laravel framework
Extension: `zip`	Required for archive handling
Extension: `opcache`	Strongly recommended for performance

Runtime Dependencies

Dependency	Notes
Node.js	Required at build time (asset compilation) and by Browsershot at runtime
npm	Required at build time for `npm ci && npm run build`
Chromium / Google Chrome	Required for PDF invoice and report generation via Spatie Browsershot

Database

PatoLab supports MySQL (recommended for production) and PostgreSQL. SQLite is supported but is intended for development and CI only.

Get Started

Core Features

Configuration

Integrations

Operations

Deploy PatoLab to Production — Server and Docker Guide

Building the image

Running the container

Docker Compose example

Database Restoration Warning

Server Requirements

PHP

Runtime Dependencies

Database

Build docs developers (and LLMs) love

Get Started

Core Features

Configuration

Integrations

Operations

Documentation Index

​Building the image

​Running the container

​Docker Compose example

​Database Restoration Warning

​Server Requirements

​PHP

​Runtime Dependencies

​Database

Build docs developers (and LLMs) love

Building the image

Running the container

Docker Compose example

Database Restoration Warning

Server Requirements

PHP

Runtime Dependencies

Database