vlauciani/ws-icon repository overview

⁠ws-icon

A lightweight web service for generating customizable icon images in various shapes (circle, square, triangle, pentagon, hexagon, star) with PNG output.

⁠Quick Start

⁠Run from Docker Hub (recommended)

docker pull vlauciani/ws-icon:latest
docker run -d --rm -p 8999:80 --name ws-icon vlauciani/ws-icon:latest

Access the service at:

• API Documentation: http://localhost:8999/⁠
• Health Check: http://localhost:8999/health.php⁠
• Example (Circle): http://localhost:8999/circle.php?xsize=60&ysize=60&bgcolor=FF0000&label=C1&textcolor=FFFFFF⁠
• Example (Square): http://localhost:8999/square.php?label=ST&labelcolor=FFFFFF&bgcolor=0000FF&dbstatuscolor=00FF00⁠

⁠Build Yourself

git clone https://github.com/vlauciani/ws-icon.git
cd ws-icon
docker build -t vlauciani/ws-icon:latest .
docker run -d --rm -p 8999:80 --name ws-icon vlauciani/ws-icon:latest

⁠Supported Icon Types

⁠Environment Variables

Example with logging:

docker run -d --rm -p 8999:80 \
  -e LOG_ENABLED=true \
  -e LOG_TO_STDOUT=true \
  --name ws-icon \
  vlauciani/ws-icon:latest

If you set LOG_ENABLED=true and LOG_TO_STDOUT=false and you want to view your log files outside the container, create log directory with full permissions:

mkdir /tmp/log
chmod 777 /tmp/log/

and mount it with: -v /tmp/log:/tmp/log. Example:

docker run -d --rm -p 8999:80 \
    -e LOG_ENABLED=true \
    -e LOG_TO_STDOUT=false \
    -v /tmp/log:/tmp/log \
    vlauciani/ws-icon:latest

⁠Key Features

• Multi-shape support: Circle, square, triangle, pentagon, hexagon, star
• Customizable: Colors, labels, borders, font sizes
• Validation: Input validation with detailed error messages (JSON format)
• Caching: Aggressive caching (1 year) for optimal performance
• CORS enabled: Ready for browser-based applications
• Health monitoring: Built-in health check endpoint
• Swagger UI: Interactive API documentation

⁠Validation Limits

• Hex colors: 6-digit hexadecimal (e.g., FF0000)
• Circle radius: 10-500 pixels
• Font size: 6-72 points
• Border size: 0-10 pixels
• Label: 1-10 characters

⁠Development

Run with live reload:

docker build -t vlauciani/ws-icon:latest .
docker run --rm -p 8999:80 \
  -e LOG_ENABLED=true \
  -e LOG_TO_STDOUT=true \
  -v $(pwd):/app \
  -v $(pwd)/log:/tmp/log \
  --name ws-icon \
  vlauciani/ws-icon:latest

⁠API Documentation

Full interactive API documentation is available at: http://localhost:8999/⁠

The legacy Swagger endpoint is still accessible at: http://localhost:8999/swagger/⁠

⁠Contribute

Contributions are welcome! See the list of contributors:

⁠

⁠License

MIT License⁠ - Copyright (c) 2025 Valentino Lauciani

⁠Author

Valentino Lauciani - vlauciani[at]gmail.com