Issues with NestJs and Puppeteer on Docker using Alpine Linux in AWS

const browserInstance = await puppeteer.start({
    execPath: process.env.EXECUTABLE_PATH_PUPPETEER,
    options: ['--no-sandbox', '--disable-setuid-sandbox'],
});
const newPage = await browserInstance.createPage();

I’m implementing this code in a NestJs service. In my AWS setup, I specified EXECUTABLE_PATH_PUPPETEER: /usr/bin/chromium-browser, but I encounter an error:

Failed to generate PDF: Browser was not found at the specified executablePath (/usr/bin/chromium-browser).

During the build process using a GitLab pipeline, I installed the following:

- echo "Beginning image setup... Including necessary tools --> aws-cli, nodejs, npm"
    # Install required tools
    - apk add --no-cache aws-cli nodejs npm
    - apk update
    - apk add --no-cache chromium nss freetype harfbuzz ca-certificates -ttf-freefont
    - chromium --version
    - which chromium-browser

The command which chromium-browser returns /usr/bin/chromium-browser, and chromium --version shows Chromium 131.0.6778.85 Alpine Linux. Despite trying numerous solutions, the initial error persists. I’ve set the environment variable to both /usr/bin/chromium-browser and /usr/bin/chromium, and I experimented with headless: true in puppeteer.start(). Any suggestions?

To resolve the issue with Puppeteer not recognizing the Chromium executable in your Alpine Linux Docker setup, you can try the following steps to ensure proper configuration:

  1. Verify Executable Path: Make sure the executable path in your environment variable matches exactly with the output from which chromium instead of chromium-browser. In Alpine Linux, it may simply be /usr/bin/chromium.
  2. <li>Install Missing Dependencies: Ensure all necessary dependencies for Chromium are installed by adding the following packages to your Dockerfile or build script:
        <pre><code>- apk add --no-cache udev ttf-freefont</code></pre>
        <p>These are crucial for Chromium and Puppeteer to run smoothly.</p>
    </li>
    
    <li>Use Correct Options: In Puppeteer, ensure you include options that allow Chromium to operate in environments like Docker without crashes:
        <pre><code>const browserInstance = await puppeteer.launch({
    executablePath: '/usr/bin/chromium', // Ensure it matches here
    args: ['--no-sandbox', '--disable-setuid-sandbox'],
    headless: true
    

    });
    const newPage = await browserInstance.newPage();

    <li>Debugging: Use Puppeteer’s debug mode to log any errors or additional information by setting the <code>PUPPETEER_DEBUG</code> environment variable to <code>true</code> before the launch. This will provide more detailed insight into where the issue might be occurring.</li>
    

These steps should help you resolve the error and generate PDFs without issues. Let me know how it goes!

In addition to the excellent advice provided by FlyingLeaf, there are a few more points to consider when troubleshooting issues with Puppeteer and Chromium in an Alpine Linux Docker setup:

  1. Update Chrome Versions: It's beneficial to ensure that the installed version of Chromium aligns with the version Puppeteer is tested against. This can often be checked and updated via Puppeteer's documentation or using a compatible release from Alpine repositories.
  2. <li><strong>Check for Symlinks:</strong> Given the path discrepancy, ensure that there are no symbolic links causing the path confusion. You can manually verify this by checking with <code>ls -l /usr/bin/chromium-browser</code> to see if it points to <code>/usr/bin/chromium</code>.</li>
    
    <li><strong>Adjust RAM and Swap:</strong> Build environments, especially in CI/CD pipelines, might have restricted resources. Increasing available RAM or swap space for the Docker container could alleviate silent crashes or unexpected behavior in Chromium.</li>
    
    <li><strong>Add Puppeteer CLI Arguments:</strong> Consider additional Puppeteer arguments that are sometimes necessary in server environments. For example:
        <pre><code>args: [
    '--no-sandbox',
    '--disable-setuid-sandbox',
    '--disable-dev-shm-usage'
    

    ],
    The –disable-dev-shm-usage flag can resolve issues related to insufficient shared memory.

    <li><strong>Utilize Docker Best Practices:</strong> Ensure your Docker container follows best practices, such as ensuring the container exits cleanly and resources are properly allocated. Sometimes, Docker-specific settings or optimizations can unexpectedly rectify performance or path issues.</li>
    
    <li><strong>Environment Verification:</strong> Log the environment variables and paths inside the Docker container as a debugging aid. It could be useful to add a step in your Dockerfile or build script that writes the full environment state to a log before the Puppeteer code is run.</li>
    

Implementing these additional steps can often resolve complex issues when combining Puppeteer with Docker and Alpine. Keep us updated on which solution worked best for your setup!