Skip to content

Home

Jump to bottom
Ethan Sholly edited this page Mar 10, 2026 · 19 revisions

Introduction

The documentation covered on this page outlines the process for deploying a container to reference and colorize selfh.st/icons via HEX color codes.

Note: The documentation below assumes users are deploying the latest container version.

AI Disclaimer

This project leverages AI to assist with development. Code contributions generated or modified with the help of AI tools are reviewed and tested by maintainers before release.

Release Notifications

Due to CDN availability constraints with jsDelivr, GitHub releases are not used when publishing updates to this container/repository.

If you'd like to be notified of new releases, sign up for e-mail notifications (no spam) using the form below:

  • E-mail (Release notes only, no spam)

Tags

Name Tag
Latest latest
Release 4.0.2, 4.0, 4

Supported Architectures

The following architectures are supported by this image. Docker will automatically detect the appropriate value for your machine - no special tags are required.

Architecture
x86-64
arm64
arm/v7

Icon Files

This image is configured to reference remote icon files by default. For local asset hosting, consider obtaining the assets using one of the following options:

  • rsync
  • Cloning the repository to a local folder
  • External tools like git-sync

Deployment

Docker

By default, no environment variables or volume mounts are required to deploy the container. Once deployed, follow the URL conventions under Building Links to begin referencing icons.

services:
  selfhst-icons:
    image: ghcr.io/selfhst/icons:latest
    container_name: selfhst-icons
    restart: unless-stopped
    ports:
      - 4050:4050

Customization

The following optional variables and volume mounts enable additional customization, including serving icons from local files.

Environment Variables

Variable Default Description
PORT 4050 Internal port for communicating with the container
PRIMARY_COLOR none HEX color variable for applying and updating a single color across icons
ICON_SOURCE remote
  • remote: Serve icons from a remote source (defaults to this repo, override with REMOTE_URL)
  • local: Serve icons from local files with mounted volumes
  • hybrid: Serve icons from local files when available, fall back to remote when not
REMOTE_URL https://cdn.jsdelivr.net/gh/selfhst/icons@main Remote URL for icons when remote or hybrid source is selected
LOG_LEVEL info
  • error: 404s, path traversals, invalid extensions, read failures
  • info: All errors, plus non-cache fetches and custom icons
  • debug: All of the above, plus cache hits
CACHE_TTL 3600 How long icons are cached in seconds
CACHE_SIZE 500 Maximum number of icons stored in cache
REMOTE_TIMEOUT 10 Seconds to wait for a remote request before timing out
CORS_ALLOWED_ORIGINS * Allowed origin(s) for cross-origin requests (must include http:// or https://)

Docker (Extended)

services:

  selfhst-icons:
    image: ghcr.io/selfhst/icons:latest
    container_name: selfhst-icons
    restart: unless-stopped
    ports:
      - 4050:4050
      
    environment:
      PORT: 4050
      PRIMARY_COLOR: 0f60d9
      ICON_SOURCE: remote
      REMOTE_URL: https://cdn.jsdelivr.net/gh/selfhst/icons@main
      LOG_LEVEL: info
      CACHE_TTL: 3600
      CACHE_SIZE: 500
      REMOTE_TIMEOUT: 10
      CORS_ALLOWED_ORIGINS: "*"
     
    # Only necessary if ICON_SOURCE is set to 'local' or 'hybrid', or if mounting custom icons alongside a 'remote' deployment
    volumes:
      - /local/path/to/svg:/app/icons/svg:ro  # Required for local/hybrid custom colors, optional if not using custom colors
      - /local/path/to/png:/app/icons/png:ro  # Optional
      - /local/path/to/webp:/app/icons/webp:ro  # Optional
      - /local/path/to/avif:/app/icons/avif:ro  # Optional
      - /local/path/to/ico:/app/icons/ico:ro  # Optional
      - /local/path/to/custom:/app/icons/custom:ro  # Optional, can be used with local or remote deployments
      
    healthcheck:
      test: ["CMD", "/server", "-healthcheck"]
      interval: 30s
      timeout: 5s
      retries: 3
      start_period: 5s

Reverse Proxy

While out of scope for this wiki, many deployments will require HTTPS. A sample Caddyfile has been provided as a reference for proxying the container.

icons.selfh.st {
    reverse_proxy selfhst-icons:4050
}

Building Links

After deployment, icons can be referenced with the following URL conventions:

Icon Valid URLs Notes
Custom Colors https://example.com/plex/0f60d9
https://example.com/plex?color=0f60d9
https://example.com/plex.svg?color=0f60d9 Use this if your application requires icon extensions in the URL
Primary Color https://example.com/plex/primary
https://example.com/plex?color=primary
https://example.com/plex.svg?color=primary Use this if your application requires icon extensions in the URL
Standard Icons https://example.com/plex No extension, defaults to WebP
https://example.com/plex.svg
https://example.com/plex.png
https://example.com/plex.webp
https://example.com/plex.avif
https://example.com/plex.ico
https://example.com/plex.gif Unsupported extension, will fall back to WebP
Custom Icon https://example.com/custom/plex.png Custom icons require a volume mount, must contain an extension in the URL, cannot be colorized, and are not limited to the extensions above

Clone this wiki locally