ImageZT

A Node.js web service that generates placeholder images with custom dimensions, colors, and text. Similar to services like placehold.it, but self-hosted.

Features

• Generate placeholder images with custom dimensions
• Customize background and foreground colors
• Add custom text (defaults to dimensions)
• Font sizing options: Specify exact font sizes in pixels or use automatic sizing
• Text wrapping: Wrap long text at word boundaries with configurable width
• Automatic font sizing based on image dimensions
• Proper color rendering for text
• Configurable caching headers for improved performance
• Environment-based configuration system
• Support for multiple image formats (PNG, JPEG, BMP)
• Configurable image quality settings
• Health check endpoint for monitoring
• Request validation and rate limiting

Table of Contents

• Installation
• Docker Usage
• Usage
• API Endpoints
• Error Handling
• Environment Configuration
• Advanced Configuration
• Dependencies
• License
• Contributing

Installation

1. Clone the repository:

git clone https://github.com/davidgoweb/imagezt.git
cd imagezt

2. Install dependencies:

npm install

Docker Usage

Using Docker Compose (Recommended)

For development:

docker-compose up -d

For production:

docker-compose -f docker-compose.prod.yml up -d

Using Docker Directly

Build the image:

docker build -t imagezt .

Run the container:

docker run -p 5930:5930 --name imagezt imagezt

Using the Pre-built Image from GHCR

Pull the image:

docker pull ghcr.io/davidgoweb/imagezt:latest

Run the container:

docker run -p 5930:5930 --name imagezt ghcr.io/davidgoweb/imagezt:latest

Environment Variables with Docker

You can pass environment variables to Docker:

docker run -p 5930:5930 \
  -e NODE_ENV=production \
  -e PORT=5930 \
  -e CORS_ENABLED=true \
  -e RATE_LIMIT_ENABLED=true \
  --name imagezt \
  imagezt

Or use an environment file:

docker run -p 5930:5930 \
  --env-file .env \
  --name imagezt \
  imagezt

Usage

Start the server:

npm start

The server will start on port 5930 by default. All configuration can be customized through environment variables.

Environment Configuration

Copy .env.example to .env and customize the settings:

cp .env.example .env

Key environment variables:

• PORT: Server port (default: 5930)
• IMAGE_FORMAT: Output format - png, jpeg, or bmp (default: png)
• IMAGE_QUALITY: Image quality for JPEG (1-100, default: 90)
• CACHE_MAX_AGE: Cache duration in seconds (default: 31536000)
• MAX_IMAGE_DIMENSION: Maximum allowed width/height (default: 5000)

Font Settings

• DEFAULT_FONT_SIZE: Default font size in pixels (8-128, default: 16)
• MIN_FONT_SIZE: Minimum allowed font size (default: 8)
• MAX_FONT_SIZE: Maximum allowed font size (default: 128)
• FONT_SIZE_AUTO_FALLBACK: Enable auto-sizing when no fontSize specified (default: true)

Text Wrapping Settings

• DEFAULT_TEXT_WRAP: Enable text wrapping by default (true/false, default: false)
• DEFAULT_TEXT_WRAP_WIDTH: Default wrap width percentage (50-95, default: 80)
• MIN_TEXT_WRAP_WIDTH: Minimum wrap width percentage (default: 50)
• MAX_TEXT_WRAP_WIDTH: Maximum wrap width percentage (default: 95)

For a complete list of environment variables, see env-config.md.

Health Check

The service includes a health check endpoint:

curl http://localhost:5930/health

Environment Check Scripts

Check your current environment configuration:

npm run env:check

Test environment variable loading:

npm run test:env

API Endpoints

Basic Usage

GET /:dims/:bgColor/:fgColor

Parameters:

• dims: Image dimensions in format WxH (e.g., 800x600)
• bgColor: Background color as 6-digit hex (without #) (e.g., ffffff)
• fgColor: Foreground/text color as 6-digit hex (without #) (e.g., 000000)

Optional Query Parameters

• text: Custom text to display on the image (defaults to dimensions)
• fontSize: Font size in pixels (8-128, defaults to auto-sizing based on image dimensions)
• textWrap: Enable text wrapping (true/false, defaults to false)
• textWrapWidth: Text wrap width as percentage of image width (50-95, defaults to 80)

Font Sizing

The service supports exact font sizes in pixels:

• Available sizes: 8, 16, 32, 64, 128 pixels
• If exact size is not available, the nearest size will be used
• When fontSize is not specified, automatic sizing based on image dimensions is used

Text Wrapping

When textWrap=true, long text will be wrapped at word boundaries:

• Text wraps within the specified percentage of image width
• Multiple lines are vertically centered
• Line height is 1.2x the font size for optimal readability

Examples

• Basic placeholder: http://localhost:5930/800x600/ffffff/000000

  • Creates an 800x600 image with white background and black text showing "800x600"

• Custom text: http://localhost:5930/400x300/ff0000/00ff00?text=Hello

  • Creates a 400x300 image with red background and green text showing "Hello"

• Custom font size: http://localhost:5930/400x300/ff0000/00ff00?text=Hello&fontSize=32

  • Creates a 400x300 image with 32px font size

• Text wrapping: http://localhost:5930/600x400/cccccc/333333?text=This is a very long text that should wrap nicely&textWrap=true

  • Creates a 600x400 image with wrapped text

• Custom wrap width: http://localhost:5930/500x300/000000/ffffff?text=Custom wrap width&fontSize=24&textWrap=true&textWrapWidth=70

  • Creates a 500x300 image with 24px font and 70% wrap width

• Small image: http://localhost:5930/100x100/cccccc/333333

  • Creates a 100x100 square with gray background and dark gray text

Error Handling

The service returns appropriate HTTP status codes for errors:

• 400: Invalid dimensions or color formats, or dimensions exceed limits
• 408: Request timeout
• 429: Too many requests (if rate limiting is enabled)
• 500: Server errors during image generation

Environment Configuration

For detailed environment variable documentation, see env-config.md.

Advanced Configuration

Security Features

• CORS support (configurable via CORS_ENABLED)
• Rate limiting (configurable via RATE_LIMIT_ENABLED)
• Request timeout protection

Performance Features

• Configurable caching headers with ETag support
• Image dimension limits to prevent resource exhaustion
• Multiple image format support with quality settings

Monitoring

• Health check endpoint for load balancers
• Configurable logging with file output support
• Debug mode for development

Dependencies

• Express - Web framework
• Jimp - Image processing library
• dotenv - Environment variable loading
• cors - CORS middleware
• express-rate-limit - Rate limiting
• morgan - HTTP request logger

License

Apache License 2.0 - see LICENSE file for details.

Contributing

1. Fork the repository
2. Create a feature branch
3. Make your changes
4. Add tests if applicable
5. Submit a pull request