mirrors/homebox
1
0
Fork 0
mirror of https://github.com/sysadminsmedia/homebox.git synced 2025-12-21 13:23:14 +01:00
Code Issues Packages Projects Releases Wiki Activity
Files
28c3e102a20f223f8777075882b427e18562818e
homebox/docs/en/custom-font-setup.md
rienkim ef52009f57 Feat/Added label maker custom font (#1038) 
* Add label maker font config

* Add document for label maker font config

* Add test for custom font

* Fix custom font setup documentation

- Fallback font is gofont which don't support CJK characters

* Fix golangci-lint error

* Update custom-font-setup.md

* Fix typo
2025-10-08 14:49:22 -04:00

2.3 KiB
Raw Blame History

External Font Support for Label Maker

Label maker supports external font files.

Quick Start

Docker/Podman Setup

  1. Download external fonts (e.g., Noto Sans KR):

  2. Create a fonts directory:

mkdir -p ./fonts
# Place your font files in this directory
# e.g., NotoSansKR-VF.ttf
  1. Mount the fonts directory and set environment variables:
# docker-compose.yml
services:
  homebox:
    image: homebox:latest
    volumes:
      - ./data:/data
      - ./fonts:/fonts:ro  # Mount fonts directory as read-only
    environment:
      - HBOX_LABEL_MAKER_REGULAR_FONT_PATH=/fonts/NotoSansKR-VF.ttf
      - HBOX_LABEL_MAKER_BOLD_FONT_PATH=/fonts/NotoSansKR-VF.ttf
    ports:
      - 3100:7745

Or with podman:

podman run -d \
  --name homebox \
  -p 3100:7745 \
  -v ./data:/data \
  -v ./fonts:/fonts:ro \
  -e HBOX_LABEL_MAKER_REGULAR_FONT_PATH=/fonts/NotoSansKR-VF.ttf \
  -e HBOX_LABEL_MAKER_BOLD_FONT_PATH=/fonts/NotoSansKR-VF.ttf \
  homebox:latest
  1. Restart the container and test label generation with Chinese, Japanese, Korean text!

Supported Fonts

  • Format: TTF (TrueType Font)
  • Recommended Fonts:
    • Noto Sans KR (Korean)
    • Noto Sans CJK (Chinese, Japanese, Korean)
    • Noto Sans SC (Simplified Chinese)
    • Noto Sans JP (Japanese)

Fallback Behavior

  1. External font specified → Tries to load from HBOX_LABEL_MAKER_*_FONT_PATH
  2. External font fails or not specified → Falls back to bundled Go fonts (Latin-only, does not support CJK characters)

Troubleshooting

Labels still show squares (□□□)

  • Check if the font file exists at the specified path
  • Verify the font file format (must be TTF, not OTF)
  • Check container logs: podman logs homebox | grep -i font

Font file not found

  • Ensure the volume is correctly mounted
  • Check file permissions (font files should be readable)
  • Use absolute paths in environment variables

Why External Fonts?

  • Smaller base image: No need to embed large font files (~10MB per font)
  • Flexibility: Easily switch fonts without rebuilding the image
  • Multi-language support: Add support for any language by mounting appropriate fonts