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 is only applicable for v2.0.0 and later.

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

The image is configured to reference remote icons file by default. Users who prefer to host the assets locally should consider one of the following options (not covered in detail in this documentation):

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

When hosted locally, users will need to un-comment the volume mount in the docker-compose template below to grant the container access to the icon files.

services:
  selfhst-icons:
    image: ghcr.io/selfhst/icons:latest
    container_name: selfhst-icons
    restart: unless-stopped
    ports:
      - 4050:4050
    environment:
      PORT: 4050
      # Set to 'remote' to use remote assets from this repo
      # Set to 'local' to use local icon files (requires volume mount)
      ICON_SOURCE: remote
      # This variable determines which icon format to use when a custom color is not specified
      # By default, this is set to 'webp' as not all icons have SVG versions
      STANDARD_ICON_FORMAT: webp
    # Volumes are only required if ICON_SOURCE is set to 'local'
    #volumes:
    #  - /local/path/to/selfhst/icons/svg:/app/icons/svg:ro  # Always required if ICON_SOURCE is 'local'
    #  - /local/path/to/selfhst/icons/png:/app/icons/png:ro  # Only required if ICON_SOURCE is 'local' and STANDARD_ICON_FORMAT is 'png'
    #  - /local/path/to/selfhst/icons/webp:/app/icons/webp:ro  # Only required if ICON_SOURCE is 'local' and STANDARD_ICON_FORMAT is 'webp'
    #  - /local/path/to/custom/icons:/app/icons/custom:ro  # Optional mount for custom local icons

While out of the scope of this guide, many applications will require users to leverage HTTPS when linking to icons served from the container.

The process to proxy the container and icons is straightforward. A sample Caddyfile configuration has been provided for reference:

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

After deployment (docker compose up), icons be referenced with the following URL conventions: