From 3e699f554c7966f3d1bec1dac74cd0bfdb6c1615 Mon Sep 17 00:00:00 2001
From: CloakHQ <cloakhq@pm.me>
Date: Tue, 28 Apr 2026 04:11:19 +0200
Subject: [PATCH] fix(docker): add emoji and extended font packages to resolve
 Kasada/Akamai canvas blocks (#179)

Dockerfile: add fonts-noto-color-emoji, fonts-freefont-ttf, fonts-unifont,
fonts-ipafont-gothic, fonts-wqy-zenhei, fonts-tlwg-loma-otf.
README: separate anti-bot font fix (apt packages) from CreepJS font
enumeration (Windows fonts + --fingerprint-fonts-dir).
---
 Dockerfile |  2 ++
 README.md  | 26 +++++++++++++-------------
 2 files changed, 15 insertions(+), 13 deletions(-)

diff --git a/Dockerfile b/Dockerfile
index a284dd0..c1951f3 100644
--- a/Dockerfile
+++ b/Dockerfile
@@ -9,6 +9,8 @@ RUN apt-get update && apt-get install -y --no-install-recommends \
     libxcb1 libxext6 libxshmfence1 \
     libglib2.0-0 libgtk-3-0 libpangocairo-1.0-0 libcairo-gobject2 \
     libgdk-pixbuf-2.0-0 libxss1 libxtst6 fonts-liberation \
+    fonts-noto-color-emoji fonts-unifont fonts-freefont-ttf \
+    fonts-ipafont-gothic fonts-wqy-zenhei fonts-tlwg-loma-otf \
     xvfb xdotool \
     curl ca-certificates \
     && curl -fsSL https://deb.nodesource.com/setup_20.x | bash - \
diff --git a/README.md b/README.md
index 8664504..39a882a 100644
--- a/README.md
+++ b/README.md
@@ -635,24 +635,24 @@ Supported by the binary but **not set by default** — pass via `args` to custom
 
 ### Font Setup on Linux
 
-**Required for aggressive anti-bot sites (Kasada, Akamai).** When running on Linux, installing Windows fonts changes how the browser renders text on canvas, which directly affects canvas fingerprint hashes. Without Windows fonts, anti-bot systems detect the Linux font rendering as inconsistent with a Windows profile and block the request. This applies even without the `--fingerprint-fonts-dir` flag — the fonts just need to be installed on the system.
+**Required for aggressive anti-bot sites (Kasada, Akamai).** These systems render emoji on a hidden canvas and hash the pixel output. Minimal Linux environments (Docker, cloud VMs) often lack emoji and extended fonts, producing hashes that don't match any real browser. Install standard font packages to fix this:
+
+```bash
+sudo apt install -y fonts-noto-color-emoji fonts-freefont-ttf fonts-unifont \
+    fonts-ipafont-gothic fonts-wqy-zenhei fonts-tlwg-loma-otf
+```
+
+The Docker image (`cloakhq/cloakbrowser`) ships with these pre-installed. If you run the binary directly on a Linux server or in a custom Docker image, install them manually.
+
+**Optional: Windows fonts for CreepJS font enumeration.** The packages above fix anti-bot canvas checks but won't improve your CreepJS font score. For that, you need actual Windows fonts (Segoe UI, Calibri, Bahnschrift, etc.) from a Windows machine's `C:\Windows\Fonts\` directory — `ttf-mscorefonts-installer` only has old XP-era fonts and isn't enough.
 
 ```bash
-# 1. Copy fonts from a Windows machine's C:\Windows\Fonts\ directory
-#    (ttf-mscorefonts-installer only has old XP-era fonts — not enough)
 mkdir -p ~/.local/share/fonts/windows
 cp /path/to/windows/fonts/*.ttf ~/.local/share/fonts/windows/
 cp /path/to/windows/fonts/*.TTF ~/.local/share/fonts/windows/
-
-# 2. Register them with fontconfig (mandatory — without this, the browser can't see them)
-fc-cache -f
-
-# 3. Launch normally — no extra flags needed
-browser = launch(headless=True, proxy="http://user:pass@proxy:port", geoip=True)
+fc-cache -f  # mandatory for manually copied fonts
 ```
 
-Optionally pass `--fingerprint-fonts-dir` to also control which fonts are visible to enumeration scripts like CreepJS:
-
 ```python
 browser = launch(
     args=["--fingerprint-fonts-dir=/home/user/.local/share/fonts/windows"],
@@ -978,9 +978,9 @@ If you're still blocked after this, check the font setup below.
 
 ### Blocked on Kasada / Akamai sites despite correct config?
 
-On Linux, missing Windows fonts changes how the browser renders canvas text, producing fingerprint hashes that anti-bot systems flag as inconsistent with a Windows profile. This is the most common cause of blocks on aggressive sites after proxy, geoip, and headed mode are already set up correctly.
+On minimal Linux environments, missing font packages cause canvas emoji rendering to produce hashes that anti-bot systems don't recognize. This is the most common cause of blocks on aggressive sites after proxy, geoip, and headed mode are already set up correctly.
 
-Install Windows fonts on your system — see [Font Setup on Linux](#font-setup-on-linux) above.
+Install the font packages listed in [Font Setup on Linux](#font-setup-on-linux) above.
 
 ---