BentoPDF Deployment and Usage Guide

1. Prerequisites

Runtime & Tools:

• Node.js (v18 or later) - Required for building and running the development server
• npm or yarn - Package manager for JavaScript dependencies
• Git - For cloning the repository
• Docker (optional) - For containerized deployment
• Podman (optional) - Alternative to Docker, especially for Podman Compose/Quadlet deployments

For Self-Hosting WASM Modules (Optional):

• Web server (Nginx, Apache, or similar) for serving WASM files
• Cloudflare account (optional) for deploying proxy workers

Accounts (Optional):

• Cloudflare account for deploying CORS proxy workers
• DigitalOcean, Vercel, Netlify, or similar for static hosting
• Docker Hub or GitHub Container Registry for container images

2. Installation

Clone the Repository

git clone https://github.com/alam00000/bentopdf.git
cd bentopdf

Install Dependencies

npm install
# or
yarn install

Verify Installation

npm run build
# Should complete without errors

3. Configuration

Environment Variables

Create a .env file in the project root for local development:

# Development server port (optional)
PORT=3000

# WASM configuration (optional - uses CDN by default)
# VITE_PYMUPDF_WASM_URL=https://cdn.jsdelivr.net/npm/@bentopdf/pymupdf-wasm/dist/
# VITE_GS_WASM_URL=https://cdn.jsdelivr.net/npm/@bentopdf/ghostscript-wasm/dist/
# VITE_CPDF_WASM_URL=https://cdn.jsdelivr.net/npm/@bentopdf/cpdf-wasm/dist/

WASM Configuration

By default, BentoPDF uses CDN-hosted WASM modules. For custom deployments:

1. Self-hosted WASM: Set the environment variables above to point to your own servers
2. Air-gapped/Offline: Pre-download WASM files and serve them locally
3. Cloudflare Proxy: Deploy the included WASM proxy worker for CORS support

Digital Signature CORS Proxy

For digital signature functionality, deploy the CORS proxy worker:

1. Navigate to the cloudflare/ directory
2. Set up wrangler.toml with your Cloudflare account ID
3. Configure environment variables:

   [vars]
   PROXY_SECRET = "your-shared-secret-here"
   

4. Deploy:

   npx wrangler deploy
   

Custom Branding

To customize the application appearance, modify:

• public/images/ - Logo and favicon files
• src/ directory - UI components and styles
• Environment variables for custom theming

4. Build & Run

Development Mode

npm run dev
# or
yarn dev

Access the application at http://localhost:3000

Production Build

npm run build
# or
yarn build

The built files will be in the dist/ directory.

Preview Production Build

npm run preview
# or
yarn preview

Docker/Podman (Single Container)

# Build the image
docker build -t bentopdf .

# Run the container
docker run -p 3000:3000 bentopdf

# With Podman
podman run -p 3000:3000 bentopdf

Docker Compose / Podman Compose (Recommended)

# Using Docker Compose
docker-compose up -d

# Using Podman Compose
podman-compose up -d

Podman Quadlet (Systemd Integration)

1. Copy the provided Quadlet configuration to ~/.config/containers/systemd/
2. Enable and start the service:

   systemctl --user enable --now bentopdf.container
   

5. Deployment

Static Hosting Platforms

BentoPDF is a static web application and can be deployed to:

Netlify:

npm run build
# Deploy the dist/ folder via Netlify CLI or drag-and-drop

Vercel:

vercel

GitHub Pages:

1. Update vite.config.ts with your base path
2. Build and deploy:

   npm run build
   # Deploy dist/ folder to gh-pages branch
   

Cloudflare Pages:

# Connect your repository and set build command:
npm run build
# Output directory: dist

Traditional Web Servers

Nginx Configuration:

server {
    listen 80;
    server_name your-domain.com;
    root /path/to/bentopdf/dist;
    
    location / {
        try_files $uri $uri/ /index.html;
    }
    
    # WASM files
    location ~ \.(wasm|js|mjs)$ {
        add_header Content-Type application/wasm;
        expires 1y;
        add_header Cache-Control "public, immutable";
    }
}

Apache Configuration:

<VirtualHost *:80>
    ServerName your-domain.com
    DocumentRoot /path/to/bentopdf/dist
    
    <Directory /path/to/bentopdf/dist>
        Options Indexes FollowSymLinks
        AllowOverride All
        Require all granted
        FallbackResource /index.html
    </Directory>
    
    # WASM MIME types
    AddType application/wasm .wasm
    AddType application/javascript .mjs
</VirtualHost>

Docker Registry Deployment

1. Build and tag your image:

   docker build -t yourusername/bentopdf:latest .
   

2. Push to registry:

   docker push yourusername/bentopdf:latest
   

3. Pull and run on your server:

   docker run -d -p 3000:3000 --name bentopdf yourusername/bentopdf:latest
   

6. Troubleshooting

Common Issues

WASM Modules Not Loading:

Error: Failed to fetch WASM module

Solution:

1. Check network connectivity
2. Verify CDN URLs in configuration
3. For local deployments, ensure WASM files are properly served with correct MIME types
4. Deploy the WASM proxy worker for CORS support

Digital Signature Errors:

CORS error when fetching certificates

Solution:

1. Deploy the CORS proxy worker from cloudflare/cors-proxy-worker.js
2. Verify PROXY_SECRET environment variable matches between worker and client
3. Check that the proxy URL is correctly configured in the application

Service Worker Cache Issues:

Old version persists after update

Solution:

1. Clear browser cache and service worker
2. Increment CACHE_VERSION in public/sw.js
3. Unregister old service workers in browser developer tools

Build Failures:

npm run build fails

Solution:

1. Ensure Node.js version is 18+
2. Clear node_modules and reinstall:

   rm -rf node_modules package-lock.json
   npm install
   

3. Check for TypeScript errors:

   npx tsc --noEmit
   

Docker/Podman Container Won't Start:

Container exits immediately

Solution:

1. Check logs:

   docker logs bentopdf
   # or
   podman logs bentopdf
   

2. Verify port mapping:

   docker run -p 3000:3000 bentopdf
   

3. Check resource limits (WASM modules require memory)

Performance Issues with Large PDFs:

Browser becomes unresponsive

Solution:

1. Use smaller PDF files (<100MB recommended)
2. Close other tabs to free memory
3. Consider using "Simple Mode" for internal use with smaller files
4. Ensure sufficient system RAM (4GB minimum, 8GB recommended)

Offline/Air-Gapped Deployment Issues:

Features don't work without internet

Solution:

1. Pre-download all WASM modules
2. Configure local URLs in environment variables
3. Ensure service worker is properly caching assets
4. Test all functionality while disconnected from network

For additional help, join the BentoPDF Discord community or consult the official documentation.