Skip to content

bbilly1/tilefy

Repository files navigation

Tilefy

Create beautiful tiles for your project

tilefy-github-stars tilefy-docker

Table of contents

Core functionality

  • Dynamically create and recreate PNG tiles
  • Showcase any project stats accessible over a public API
  • Customize to your liking with your branding and color scheme
  • Embed your tiles anywhere you can embed a image
  • Self Hosted with Docker

Screenshots

home screenshot

Installation

Take a look at the example docker-compose.yml file provided. Tilefy depends on two containers:

Tilefy

Main Python application to create and serve your tiles, built with Flask.

  • Serves the interface on port 8000
  • Needs a volume at /data to store your tiles, custom fonts and logos and your tiles.yml config file.
  • Set your Redis connection with the environment variables REDIS_HOST and REDIS_PORT.
  • Set the environment variable TILEFY_HOST to your full url from where you are hosting this application. Needed to build links and templates to embed your tiles. Don't add a trailing /.
  • Set your timezone with the TZ environment variable to configure the scheduler, defaults to UTC.

Redis JSON

Functions as a cache, holds your configurations.

  • Needs a volume at /data to store your configurations permanently.

Configuration

Create a yml config file at /data/tiles.yml. Take a look at the provided tiles.example.yml for the basic syntax. tiles is the top level key, list your tiles below. The main key of the tile is your slug and will become your url, so use no spaces or special characters.

tile_name

Give your tile a unique human readable name.

background_color, font_color

Hex color code for background and font, make sure to add the "" to escape the # symbol.

width, height

Size of the tile in pixels.

logos

List of logos, get a list of pre installed logos:

docker exec -it tilefy ls logos

Add the pre installed logos by providing the file name. Contribute by adding additional commonly used logos.

Provide your custom logos by adding them to /data/logos/, in PNG file format with transparent background. Add your custom logos by providing a relative path like logos/file-name.png.

font: optional

Font defaults to Vera.ttf. Use a pre installed font from the liberation or ttf-bitstream-vera packages by providing the relative path from the truetype folder. List available pre installed fonts:

docker exec -it tilefy ls /usr/share/fonts/truetype/liberation
docker exec -it tilefy ls /usr/share/fonts/truetype/ttf-bitstream-vera

Provide your custom font by adding them to /data/fonts, in TTF format only and add them with their relative path like fonts/font-name.ttf.

humanize: optional

Defaults to true for all numbers. Shorten long numbers in to a more human readable string, like 14502 to 14.5K.

recreate: optional

Set the lifetime of your tiles and define when the tile will be recreated if requested. Defaults to 1d, e.g. recreate every day.

Valid options:

  • 120: A number indicates seconds till expire
  • 10min: Minutes till expire
  • 2h: Hours till expire
  • 1d: Days till expire
  • on_demand: Will recreate for every request.

Note:

  • Be aware of any rate limiting and API quotas you might face with a too short expiration.
  • There is a failsafe in place to block recreating tiles faster than every 60 seconds.

API requests

Get values from a public API by providing the url and key_map.

url

JSON API endpoint. If you can, filter and reduce the API response size by requesting only the required fields.

key_map

Navigate the JSON object to find your desired value. Each item in the list navigates one level deeper, a string accesses a key and a int accesses an index in an array.

Example 1

{
    "pull_count": 269912,
    "star_count": 11,
}

To for example access the pull_count key in the top level of the response:

key_map:
  - pull_count

Example 2

{
    "results": [
        {
            "status": "success",
            "last_run": "timestamp",
        }
    ]
}

To for example access the status key in the first dictionary of the results list:

key_map:
  - results
  - 0
  - status

Plugins

For all values not accessible over a JSON API endpoint, this will need a dedicated solution by for example scraping the website. This is inherently less reliable as websites change more frequently than APIs.

Chrome extension users

Get the amount of active chrome extension users.

plugin:
  name: chrome-extension-users
  id: jjnkmicfnfojkkgobdfeieblocadmcie

Please contribute and open feature requests to add more.

Donate

The best donation to Tilefy is your time, contribute in any way you can to improve this project.
Second best way to support the development is to provide for caffeinated beverages: