Docker Alpine wkhtmltopdf: Solving the Chinese and Thai Character Display Issue
Problem: When using wkhtmltopdf in a Docker container based on Alpine Linux, you might encounter issues with displaying Chinese and Thai characters correctly. The rendered PDF often shows gibberish or unexpected symbols instead of the intended characters.
Rephrasing: Imagine you want to generate a PDF document with Chinese or Thai text using Docker and wkhtmltopdf. The problem is that the generated PDF might show strange symbols instead of the actual text. This is a common issue when using Alpine Linux as the base image.
Scenario & Code:
Let's say you have a simple HTML file (index.html) containing Chinese and Thai text:
<!DOCTYPE html>
<html lang="en">
<head>
<meta charset="UTF-8">
<title>Document</title>
</head>
<body>
<h1>你好，世界！</h1>
<h2>สวัสดีครับ</h2>
</body>
</html>
And a Dockerfile to build your container:
FROM alpine:latest
RUN apk add --update wkhtmltopdf
COPY index.html /app/index.html
CMD ["wkhtmltopdf", "/app/index.html", "/app/output.pdf"]
Running this Dockerfile might result in a PDF with the Chinese and Thai characters displayed incorrectly.
Analysis & Insights:
This issue arises because Alpine Linux uses a different font configuration than most other Linux distributions. It often lacks the necessary fonts for displaying Chinese and Thai characters correctly. To fix this, we need to install the required fonts within the Docker container.
Solution:
-
Install the Fonts:
- For Chinese: Use the
fontconfigandttf-chinese-fontspackages:RUN apk add --update fontconfig ttf-chinese-fonts - For Thai: Use the
fontconfigandttf-thai-fontspackages:RUN apk add --update fontconfig ttf-thai-fonts - For both: Install both packages:
RUN apk add --update fontconfig ttf-chinese-fonts ttf-thai-fonts
- For Chinese: Use the
-
Rebuild your Docker image:
docker build -t my-wkhtmltopdf .
-
Run the container:
docker run -it my-wkhtmltopdf
Additional Considerations:
- Font selection: You can customize the font used for specific languages by adding
--use-xserverand--no-stop-slow-scriptsto yourwkhtmltopdfcommand. - Alternative base images: If you prefer a more comprehensive font selection, you can use a different base image like
ubuntuordebian. - Using a font file: If you need a specific font, you can download the font file and copy it to your container. Then, you can use the
--font-familyoption inwkhtmltopdfto specify the font path.
Conclusion:
By installing the necessary fonts within your Docker container, you can ensure correct display of Chinese and Thai characters when using wkhtmltopdf on Alpine Linux. This approach helps you create professional-looking PDF documents with multilingual support.
References:
Additional Value:
This article provides a practical solution to a common issue encountered when working with wkhtmltopdf on Alpine Linux. It explains the problem in detail, offers a clear solution, and provides additional tips and considerations for optimizing your workflow.
