Process required for a working install on Forge provisioned servers (Digital Ocean)

[KS-Verbosity]

What happened?

So far it has not been possible to get an application into production as all attempts at a Forge solution have failed. Many attempts have been made and at best the result is the same as what is listed in Discussion 93 - #93
Definitely looking for updated guidance. I will report any success if I find a solution.

How to reproduce the bug

Move a working Laravel 10 app with the PDF tool installed (from MacOS using Herd Pro). Everything works fine locally, but it has not been possible to get a working install done on a Forge server (Digital Ocean).

Package Version

1.1

PHP Version

8.2.15

Laravel Version

10.45.1

Which operating systems does with happen with?

Linux

Notes

Digital Ocean server
/home/forge/.nvm/versions/node/v21.7.1/bin/node
npm updated
Errors such as these are as close as it gets to working:
The command "PATH=$PATH:/usr/local/bin:/opt/homebrew/bin NODE_PATH=/home/forge/.nvm/versions/node/v21.7.1/bin/node /home/forge/.nvm/versions/node/v21.7.1/bin/npm root -g /home/forge/.nvm/versions/node/v21.7.1/bin/node '/home/forge/xxx.com/vendor/spatie/browsershot/src/../bin/browser.cjs' ''" failed.

Exit Code: 1(General error)

Error Output:

Error: net::ERR_FILE_NOT_FOUND at file:///tmp/106890602-0196505001711765888/index.html
at navigate (/home/forge/xxx.com/node_modules/puppeteer-core/lib/cjs/puppeteer/cdp/Frame.js:171:27)
at process.processTicksAndRejections (node:internal/process/task_queues:95:5)
at async Deferred.race (/home/forge/xxx.com/node_modules/puppeteer-core/lib/cjs/puppeteer/util/Deferred.js:36:20)
at async CdpFrame.goto (/home/forge/xxx.com/node_modules/puppeteer-core/lib/cjs/puppeteer/cdp/Frame.js:137:25)
at async CdpPage.goto (/home/forge/xxx.com/node_modules/puppeteer-core/lib/cjs/puppeteer/api/Page.js:590:20)

[Janqu]

Working solution for me

Maybe it will solve your problem too.

Error Output

My problem with Hetzner Cloud Ubuntu 22.04 and Laravel 11
Development environment is also Herd Pro on MacOS

Symfony\Component\Process\Exception\ProcessTimedOutException The process "PATH=$PATH:/usr/local/bin:/opt/homebrew/bin NODE_PATH=npm root -g node 'vendor/spatie/browsershot/src/../bin/browser.cjs' '{"url":"file:///tmp/194482169-0286861001711839596/index.html","action":"pdf","options":{"path":"invoice.pdf","args":[],"viewport":{"width":800,"height":600},"displayHeaderFooter":false,"printBackground":true}}'" exceeded the timeout of 60 seconds.

[115372:115372:0330/231700.707395:ERROR:zygote_host_impl_linux.cc(100)] Running as root without --no-sandbox is not supported. See https://crbug.com/638180.

[kaspernowak]

Hey @KS-Verbosity, I struggled a lot with getting this to work on my ubuntu server with openlitespeed, but I got it to work eventually, see this: #134 (comment)

[RedskyThirty]

I also encountered numerous issues getting "Spatie\LaravelPdf" to work on a remote server, even though everything worked perfectly right away on my local environment.
Since I lost a lot of time, I wrote a file detailing everything I did. Some actions were probably unnecessary, but I included them just in case.
I'm sharing the file with you, it might help someone someday.

P.S.: As you will notice, some actions are repeated, but I encountered error after error, and it was in this order that I resolved my issues.

Troubleshooting Guide for Spatie\LaravelPdf and Browsershot

Context

The library "Spatie\LaravelPdf" uses "Browsershot", which depends on "Puppeteer" and "Chromium" to generate PDFs and screenshots. These dependencies require at least Node.js 22.0 to be installed on the server. Additional details can be found here:

• Spatie Browsershot Requirements

Issue on Hetzner Servers

There is a known issue on Hetzner servers where the URLs in the configuration files for updating internal packages are incorrect. If errors occur when running sudo apt update, follow these steps:

1. Fix the incorrect URLs in apt sources:

   • Connect to the server using SSH.
   • Edit the file /etc/apt/sources.list and replace all URLs beginning with https://mirror.hetzner.com/ubuntu/ with http://mirror.hetzner.com/ubuntu-ports/.

2. Preserve updated URLs:

   • Edit the file /etc/cloud/cloud.cfg and add the following content:

     # Preserve updated URLs in "/etc/apt/sources.list"
     apt_preserve_sources_list: true

Upgrading Node.js and NPM

If the installed version of Node.js is lower than 22:

1. Follow the instructions described here: Upgrading Node.js.
2. Upgrade NPM if needed: Upgrading NPM.

---

Steps Taken to Resolve the Issue

Install Chromium and Configure Puppeteer

# Install Chromium, as it's required by Puppeteer to render PDFs and screenshots
sudo apt install -y chromium-browser

# Set the environment variable for Puppeteer to use the installed Chromium browser
export PUPPETEER_EXECUTABLE_PATH=/usr/bin/chromium-browser

# Clear Puppeteer's cache to remove any corrupted or outdated files
rm -rf ~/.cache/puppeteer

# Force reinstall Puppeteer to ensure it is properly set up
npm install puppeteer --force

Install Missing Dependencies

Chromium requires several system dependencies to function correctly. Install them using:

# Sources:
# https://pptr.dev/guides/system-requirements
# https://source.chromium.org/chromium/chromium/src/+/main:chrome/installer/linux/debian/dist_package_versions.json

sudo apt update && sudo apt install -y \
    libasound2 \                # Audio support library
    libatk-bridge2.0-0 \        # Accessibility toolkit bridge
    libatk1.0-0 \               # Accessibility toolkit library
    libgtk-3-0 \                # Graphical toolkit
    libatspi2.0-0 \             # Assistive Technology Service Provider Interface
    libc6 \                     # GNU C library
    libcairo2 \                 # Vector graphics rendering library
    libcups2 \                  # Printing system support library
    libdbus-1-3 \               # D-Bus IPC system
    libdrm2 \                   # Direct Rendering Manager
    libexpat1 \                 # XML parsing library
    libgbm1 \                   # Graphics buffer manager
    libglib2.0-0 \              # GLib utilities
    libnspr4 \                  # Netscape Portable Runtime
    libnss3 \                   # Network Security Services
    libpango-1.0-0 \            # Text layout and rendering
    libpangocairo-1.0-0 \       # Pango library for Cairo rendering
    libstdc++6 \                # Standard C++ library
    libudev1 \                  # Device management library
    libuuid1 \                  # UUID library
    libx11-6 \                  # X11 client-side library
    libx11-xcb1 \               # X11-XCB utility
    libxcb-dri3-0 \             # XCB Direct Rendering Infrastructure
    libxcb1 \                   # X protocol C-language binding
    libxcomposite1 \            # X11 composite extension
    libxcursor1 \               # X11 cursor management library
    libxdamage1 \               # X11 damage extension
    libxext6 \                  # X11 miscellaneous extensions
    libxfixes3 \                # X11 region manipulation library
    libxi6 \                    # X Input extension
    libxkbcommon0 \             # Keyboard handling library
    libxrandr2 \                # X Resize and Rotate extension
    libxrender1 \               # X Rendering extension
    libxshmfence1 \             # Shared memory fence synchronization
    libxss1 \                   # X11 screensaver extension
    libxtst6                   # X11 test extension

Install Additional Utilities

Some Chromium features require xdg-utils. Install it using:

sudo apt install -y xdg-utils

Resolve Chromium Installation Conflicts

1. Remove Chromium installed via Snap to avoid version conflicts:

   sudo snap remove chromium

2. Reinstall Chromium using apt:

   sudo apt install -y chromium-browser

3. Reinstall Chromium via Snap as a fallback:

   sudo snap install chromium

---

Code Configuration for Browsershot

Pdf::view('path.to.view', []) // Specify the view to render as a PDF
    ->withBrowsershot(function (Browsershot $browsershot) {
        /*
         * Only apply these configurations in non-development environments
         * as the library works correctly in local environment
         */
        
        if (!is_development()) {
            $browsershot
                ->setChromePath('/usr/bin/chromium-browser') // Use manually installed Chromium
                ->setCustomTempPath(storage_path('temp'))    // Custom temp directory for server compatibility
                ->noSandbox()                                // Disable sandbox for headless Chromium compatibility
                ->newHeadless();                             // Run Chromium in headless mode
        }
    });

[RedskyThirty]

I’m following up on my message from yesterday, and unfortunately, I have bad news: nothing is working on the server anymore. In reality, it’s very inconsistent... Sometimes I get an error, then after a few minutes, it starts working again, only to fail again a few minutes later.

I suspect the server is taking too long to start Chromium, or it struggles to do so, but once it’s running, everything works fine until the service shuts down.

In short, my solution above makes the library functional, but there’s something else causing issues. I’ve spent enough time on this, so I’m switching to another library.

[RedskyThirty]

I switched to laravel-dompdf.
This library does not support CSS flexbox and CSS grid but it works.