mirror of
https://github.com/bbilly1/tilefy.git
synced 2024-08-02 16:03:34 +00:00
140 lines
5.4 KiB
Markdown
140 lines
5.4 KiB
Markdown
|
![Tilefy](assets/tilefy-banner.jpg?raw=true "Tilefy Banner")
|
||
|
|
||
|
<center><h1>Create beautiful tiles for your project</h1></center>
|
||
|
|
||
|
## Table of contents
|
||
|
- [Core functionality](#core-functionality)
|
||
|
- [Screenshots](#screenshots)
|
||
|
- [Installation](#installation)
|
||
|
- [Configuration](#configuration)
|
||
|
- [API requests](#api-requests)
|
||
|
- [Plugins](#plugins)
|
||
|
- [Donate](#donate)
|
||
|
|
||
|
## 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](assets/screenshot.png?raw=true "Tilefy Home Page")
|
||
|
|
||
|
## 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 and holds the scheduler data storage and history.
|
||
|
- Needs a volume at **/data** to store your configurations permanently.
|
||
|
|
||
|
## Configuration
|
||
|
Create a yml config file where you have mounted your `/data/tiles.yml` folder. 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:
|
||
|
```bash
|
||
|
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:
|
||
|
```bash
|
||
|
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
|
||
|
Recreate tiles periodically, provide your custom schedule as a cron tab or use `on_demand` to recreate the tile for every request. Defaults to `0 0 * * *` aka every day at midnight. Be aware of any rate limiting and API quotas you might face with a too frequent schedule.
|
||
|
Note:
|
||
|
- There is automatically a random jitter for cron tab of 15 secs to avoid parallel requests for a lot of tiles.
|
||
|
- 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*
|
||
|
```json
|
||
|
{
|
||
|
"pull_count": 269912,
|
||
|
"star_count": 11,
|
||
|
}
|
||
|
```
|
||
|
To for example access the *pull_count* key in the top level of the response:
|
||
|
```yml
|
||
|
key_map:
|
||
|
- pull_count
|
||
|
```
|
||
|
|
||
|
*Example 2*
|
||
|
```json
|
||
|
{
|
||
|
"results": [
|
||
|
{
|
||
|
"status": "success",
|
||
|
"last_run": "timestamp",
|
||
|
}
|
||
|
]
|
||
|
}
|
||
|
```
|
||
|
|
||
|
To for example access the *status* key in the first dictionary of the results list:
|
||
|
```yml
|
||
|
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.
|
||
|
```yml
|
||
|
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:
|
||
|
* [Paypal.me](https://paypal.me/bbilly1) for a one time coffee
|
||
|
* [Paypal Subscription](https://www.paypal.com/webapps/billing/plans/subscribe?plan_id=P-03770005GR991451KMFGVPMQ) for a monthly coffee
|
||
|
* [ko-fi.com](https://ko-fi.com/bbilly1) for an alternative platform
|