Update docs and make compile accept more installation type

Author: Thomas-Boi

Buildpacks.PNG

@@ -1,21 +1,66 @@
-# heroku-playwright-chromium
-A buildpack to install the Playwright Chromium executable ONLY. 
+# heroku-playwright-python-browsers
+A buildpack to install Playwright browser executables for usage with Python on Heroku. 
 
+**NOTE**: this buildpack and the following instructions was developed for usage with Chromium in mind. It is likely to work with Firefox and Webkit as well BUT hasn't been tested by the author. You are on your own when using Firefox and Webkit since I don't use those tools. Let me know if this buildpack works though and I'll update the docs.
 
 # Usage
 
-1. Add this buildpack to your app alongside the [heroku-playwright-buildpack](https://github.com/playwright-community/heroku-playwright-buildpack).
-  - The script CANNOT install the system requirements due to restrictions from Heroku. It's only able to install the Chromium exe. 
-  - Thus, we rely on [heroku-playwright-buildpack](https://github.com/playwright-community/heroku-playwright-buildpack) to get the other packages.
-2. Run and deploy
+Follow the steps below.
 
-# Customization
-By default, this will install the necessary exe into a folder called `/browsers` under the build directory (the directory where the root script lives).
+## Tell Python to install `playwright`
 
-To change the this folder's name, override the `INSTALL_PATH` environmental variable.
+This buildpack relies on the CLI command `playwright install`. This requires [`playwright`](https://pypi.org/project/playwright/) to be installed. Do this by specifying a `requirements.txt` or any other methods accepted by the Heroku Python buildpacks.
 
-# Notes
-This was developed for usage with `playwright-python` in mind so support for other languages is unknown.
+## Buildpack ordering
+
+Order matters for this buildpack to work. Here's the run order that you should should have:
+
+![Buildpack Image](Buildpacks.PNG)
+
+1. The official [Python buildpack](https://elements.heroku.com/buildpacks/heroku/heroku-buildpack-python).
+  - Runs first so that Playwright is available as a CLI tool after the package installation is done
+1. This build pack. [Here's how to add this buildpack to your app](https://devcenter.heroku.com/articles/buildpacks#using-a-third-party-buildpack) by using its Git URL.
+2. The [heroku-playwright-buildpack](https://github.com/playwright-community/heroku-playwright-buildpack)
+  - **Why?** This buildpack CANNOT install system requirements (i.e. `playwright install --with-deps`) due to restrictions from Heroku. It's only able to install the browser executables. Thus, we rely on [heroku-playwright-buildpack](https://github.com/playwright-community/heroku-playwright-buildpack) to get the needed system packages.
+
+
+## Customize the following config variables:
+1. `PLAYWRIGHT_BUILDPACK_BROWSERS` accepts a comma-separated list of the browser names `chromium,firefox,webkit`. By default, it's installing the executables for all these browsers. 
+  - E.g. To only install Chromium dependencies, set the variable to `chromium`. This will reduce the slug size in the end too. 
+    - **NOTE**: this is what the author uses, usage with the other 2 browsers are unknown. Feel free to test them out and let me know if they work and I'll update the docs.
+  - This config variable is intended to be shared with [heroku-playwright-buildpack](https://github.com/playwright-community/heroku-playwright-buildpack).
+2. `BUILDPACK_BROWSERS_INSTALL_PATH` is the path where the browsers will be installed. Its default value is `browsers` and it's a relative path starting from the [`BUILD_DIR`](https://devcenter.heroku.com/articles/buildpack-api#bin-compile) (the starting directory of the compiled slug to be used by Heroku). It's necessary to have the installed browsers within the `BUILD_DIR` to have the file included by the time Heroku starts the dyno.
+  - E.g. To install in the directory `utils/browsers`, set the variable to `utils/browsers`.
+  - This config variable is exported by the buildpack for your use in the next step
+
+## Modify your browser init script
+
+Since the browsers are installed in a non-default location, we have to specify the executable path when we create the browser instances.
 
+Here's how you should create your browser:
 
+```
+with sync_playwright() as p:
+  try:
+      browser = p.chromium.launch(executable_path=env("CHROME_EXECUTABLE_PATH"), ...other arguments)
+      # for chromium, you don't have to pass in flags like `no-sandbox` or `headless` because they are enabled by default.
+      # Flags like `--disable-dev-shm-usage` and `--remote-debugging-port=9222` can be added if needed but I haven't needed that
+```
+
+
+# Questions
+
+**1. Why doesn't this buildpack install the requirements as well?**
+
+The command to install the system packages along with the browser is `playwright install --with-deps`. For some reason, this action is blocked by Heroku since it uses sudo underneath (which is not allowed as of 2024). Thus, only the browser installation can go through but that alone is not enough. We still need the system packages which is provided by `heroku-playwright-buildpack`.
+
+**2. The script doesn't work for me. What do I do?**
+
+Here are a few things to consider:
+- This buildpack is meant for Python Playwright and was developed with Chromium in mind. Any other browser/Playwright distro is not tested by me so I offer no guarantees there
+- Verify that the installation is successful. Look at the build logs, you should see progress bar for the executable installations
+  - You can also `heroku run bash` into the dyno and search for the installation folder to verify that the exe are downloaded.
+
+# Notes
+This was developed for usage with `playwright` for Python
 

README.md

@@ -4,14 +4,30 @@
 set -e
 
 BUILD_DIR=$1
+ENV_DIR=$3
 
 # modify the installation location
-if [ -z "$INSTALL_PATH" ]; then
-  INSTALL_PATH="/browsers"
+if [ -z "$BUILDPACK_BROWSERS_INSTALL_PATH" ]; then
+  BUILDPACK_BROWSERS_INSTALL_PATH="/browsers"
 fi
 
-export PLAYWRIGHT_BROWSERS_PATH=$BUILD_DIR/$INSTALL_PATH
-echo "-----> Install path is $INSTALL_PATH"
+if [ -z "$PLAYWRIGHT_BUILDPACK_BROWSERS" ]; then
+  SUPPORTED_BROWSERS=${PLAYWRIGHT_BUILDPACK_BROWSERS:-chromium,firefox,webkit}
+	echo "Installing Playwright dependencies (env: PLAYWRIGHT_BUILDPACK_BROWSERS) for $SUPPORTED_BROWSERS."
+fi
+
+export PLAYWRIGHT_BROWSERS_PATH=$BUILD_DIR/$BUILDPACK_BROWSERS_INSTALL_PATH
+echo "-----> BROWSERS_INSTALL_PATH is $BUILDPACK_BROWSERS_INSTALL_PATH"
 echo "-----> Browsers will be installed in $PLAYWRIGHT_BROWSERS_PATH"
-playwright install chromium
-echo "-----> Installation done"
+echo "-----> Formatted values are ${SUPPORTED_BROWSERS/,/ }"
+playwright install ${SUPPORTED_BROWSERS/,/ }
+echo "-----> Installation done"
+
+# export the file path as a ENV
+CHROMIUM_EXECUTABLE_PATH=${find ~+ -type f -name "chrome"}
+FIREFOX_EXECUTABLE_PATH=${find ~+ -type f -name "geckodriver"}
+WEBKIT_EXECUTABLE_PATH=${find ~+ -type f -name "webkit"}
+
+if [ -v "$CHROMIUM_EXECUTABLE_PATH" ]; then
+  echo $CHROMIUM_EXECUTABLE_PATH > $ENV_DIR/CHROMIUM_EXECUTABLE_PATH
+fi