Laravel PDF (Spatie) + Puppeteer + Forge: “No usable sandbox” error in production

The error you're encountering is related to Puppeteer trying to launch a headless browser on a server without the necessary sandboxing capabilities. This is a common issue when running Puppeteer on Linux servers, especially when using a minimal setup like those often found on cloud hosting services.

Here’s how you can resolve the "No usable sandbox" error:

1. Install Necessary Dependencies:

   Puppeteer requires certain system dependencies to run properly. You can install these on your Ubuntu server using the following command:

   sudo apt-get update
   sudo apt-get install -y \
     gconf-service \
     libasound2 \
     libatk1.0-0 \
     libc6 \
     libcairo2 \
     libcups2 \
     libdbus-1-3 \
     libexpat1 \
     libfontconfig1 \
     libgcc1 \
     libgconf-2-4 \
     libgdk-pixbuf2.0-0 \
     libglib2.0-0 \
     libgtk-3-0 \
     libnspr4 \
     libpango-1.0-0 \
     libpangocairo-1.0-0 \
     libstdc++6 \
     libx11-xcb1 \
     libxcomposite1 \
     libxdamage1 \
     libxext6 \
     libxfixes3 \
     libxrandr2 \
     libxrender1 \
     libxss1 \
     libxtst6 \
     ca-certificates \
     fonts-liberation \
     libappindicator1 \
     libnss3 \
     lsb-release \
     xdg-utils \
     wget
   

2. Disable the Sandbox:

   If installing the dependencies does not resolve the issue, you can try running Puppeteer without the sandbox. This is generally not recommended for production environments due to security concerns, but it can be a temporary workaround.

   You can disable the sandbox by adding the --no-sandbox and --disable-setuid-sandbox flags to the Puppeteer launch options. In the context of the spatie/laravel-pdf package, you can configure this in your Laravel code:

   use Spatie\Browsershot\Browsershot;
   
   Browsershot::html('<h1>Hello world!</h1>')
       ->noSandbox()
       ->save('example.pdf');
   

   The noSandbox() method is a convenience method provided by Browsershot to add these flags.

3. Consider Security Implications:

   If you choose to disable the sandbox, be aware of the security implications. Running without a sandbox can expose your server to potential vulnerabilities. If possible, consider running Puppeteer in a more secure environment or using a different approach to generate PDFs.

By following these steps, you should be able to resolve the "No usable sandbox" error and successfully generate PDFs on your Forge provisioned server.