Server configuration¶
The whole server is configured by one file, config.yaml. Start from config-example.yaml.
Where the file lives¶
With the supplied docker-compose.yml the server reads ./config.yaml from the project folder (mounted read-only at /config/config.yaml). Your own pages go into ./pages-custom (mounted at /config/pages, see Writing pages). Create that folder before the first start (mkdir pages-custom), otherwise Docker creates it as root.
After every change restart the server:
docker compose restart
docker compose logs --tail 50
The server checks the file at startup. If something is wrong (a typo in a key, an unknown page type, a refresh below the minimum) it refuses to start and prints a clear message to the log.
Top-level options¶
| Key | Default | Meaning |
|---|---|---|
interval |
30 |
Default display time of a page in seconds. |
timezone |
Europe/Berlin |
Time zone for clocks and times on pages (IANA name). |
lang |
de |
Default language of the built-in pages (de or en). |
custom_pages_dir |
not set | Folder with your own page types. Relative paths are relative to the config file. It may be missing, the server then logs a warning and uses the built-in pages only. In Docker use /config/pages. |
push_key |
not set | Key for pushed data (needed by the ai page with provider claude). At least 16 characters, ASCII only (letters, digits, -, _); generate one with openssl rand -hex 24. Without it the push endpoint is off. Use it on your home network only (LAN). Put it in .env and write push_key: ${GLANCEBOX_PUSH_KEY}. |
pages |
required | The playlist, at least one page. |
Unknown top-level keys are rejected.
Secrets and environment variables¶
Never write tokens or keys into config.yaml. Put them in a file called .env next to docker-compose.yml, one NAME=value per line, and refer to them in the config:
push_key: ${GLANCEBOX_PUSH_KEY}
- Only a value that is exactly
${NAME}is replaced. Inside a longer text such ashttp://${HOST}:3001it stays literal text. - The server refuses to start if the variable is missing or empty and names the place in the file, for example
pages[2].token: environment variable KUMA_TOKEN is not set. - A replaced value is always text. Options that need a number, such as
refreshorbudget, cannot use${NAME}. - Docker reads
.envonly when the container is created. After a change rundocker compose up -d;docker compose restartdoes not apply it. - The supplied
docker-compose.ymlloads.envwithenv_fileandpath/required: false, so the file may be missing. This form needs Docker Compose 2.24 or newer (docker compose version).
Options every page has¶
pages:
- type: clock
duration: 15
refresh: 60
| Key | Default | Meaning |
|---|---|---|
type |
required | Page type: url, bahn, clock, weather, kuma, homeassistant, ai or one of your own. The ready-made ones are described in the template catalog. |
duration |
interval |
How many seconds the page stays on the display. |
refresh |
duration |
A page is rendered again at most every refresh seconds. Use a larger value for data that changes slowly or for services that limit requests. |
All other keys belong to the page type and are described below. Ready-made pages with preview pictures are in the template catalog.
Page type: url¶
Renders a web page as it is, in a browser window of exactly 240x240 pixels.
- type: url
url: http://homeserver.lan/status-240
wait_for: "#ready"
wait_ms: 500
duration: 15
refresh: 30
| Key | Default | Meaning |
|---|---|---|
url |
required | http:// or https:// address. |
wait_for |
none | CSS selector. The screenshot is taken only after an element matching it exists. Use this for pages that build their content with JavaScript. |
wait_ms |
0 |
Extra pause in milliseconds before the screenshot (after the page loaded and wait_for matched). |
timeout_s |
15 |
How long loading and wait_for may take before the page counts as failed. |
The server runs in a container. localhost there means the container itself, so use the LAN address or name of the other machine. Pages that need a login show the login screen. Tips for designing such pages are in Writing pages.
Page type: bahn¶
Live departures for a German station, from DBF (db-infoscreen).
- type: bahn
station: "Frankfurt(Main)Hbf"
via: [Wiesbaden, Mainz]
platforms: "101,102"
limit: 4
title: "Frankfurt"
refresh: 60
| Key | Default | Meaning |
|---|---|---|
station |
required | Station name, EVA number or DS100 code. Find the exact name on dbf.finalrewind.org: the part of the address after the search. |
via |
all | Only trains that stop at one of these places after your station (text or list). Intermediate stops work better than final destinations, because they also catch trains that end earlier. |
platforms |
all | Only these platforms (text or list). |
limit |
4 |
Rows, 1 to 6. Fewer rows mean bigger text. |
title |
the station | Header text. |
dbf_url |
https://dbf.finalrewind.org |
Address of a DBF instance, if you run your own. |
refresh |
60 |
At least 60. This is DBF's rule of one request per station and minute. If you do not set refresh it is raised to 60 automatically. If you set a value below 60 the server refuses to start. |
If DBF cannot be reached the page shows "Keine Daten", an empty list shows "Keine Abfahrten". Full description: bahn.
Page type: clock¶
A large clock with weekday and date, meant as the starting point for your own pages. Full description: clock.
- type: clock
lang: en
refresh: 60
| Key | Default | Meaning |
|---|---|---|
lang |
top-level lang |
de or en. |
Page type: weather¶
Current weather, today's high and low and the next 4 hours, from Open-Meteo (free, no key). Full description: weather.
- type: weather
location: Frankfurt am Main # or latitude: / longitude:
Page type: kuma¶
The state of your server from an Uptime Kuma status page: a big "14/14 OK", or a red header with the services that are down. No token and no rights on your server. Full description, including how to install Uptime Kuma: kuma.
- type: kuma
url: http://homeserver.lan:3001
slug: homelab
refresh: 30
Page type: homeassistant¶
Live values of up to six Home Assistant entities, as tiles (1 to 4) or a list (up to 6). Needs a long-lived access token; put it and the address in .env, see Secrets and environment variables. The token has all the rights of its user, so use a separate user. Full description: homeassistant.
- type: homeassistant
url: ${HA_URL}
token: ${HA_TOKEN}
title: Solar
refresh: 30
entities:
- sensor.pv_power
- entity: sensor.grid_power
label: Grid
Page type: ai¶
How much of an AI plan or budget you have used, one provider per page: claude (plan limits, sent by Claude Code on your computer), anthropic-api, openai-api, xai-api (cost or credit) and copilot (monthly usage). Keys belong in .env, see Secrets and environment variables. Full description and setup per provider: ai.
- type: ai
provider: claude
refresh: 30
How the playlist behaves¶
- The page currently shown follows from the clock: the durations of all pages add up to one cycle, and the position in the cycle is the current time modulo that sum. The server keeps no state per device, so several displays show the same page at the same time.
- The display asks the server for the next picture after the time the server names. That time is always between 2 and 30 seconds. The picture only travels if it changed, otherwise the server answers "not modified".
- Pictures are baseline JPEGs of 240x240 pixels and at most 24 576 bytes. The server lowers the quality (from 85 down to 40) until a picture fits. Very detailed images (photos, fine gradients) may still fail, flat colors work best.
- If a page fails (data source down, template error), the server keeps showing its last good picture for up to 10 minutes. After that the page is skipped. If no page works at all, the display shows an error page instead of a black screen. Errors are in the log and on the preview page.
Checking and operating the server¶
| Address | What it does |
|---|---|
http://<server>:8080/ |
Preview of all pages with age and last error (refreshes itself). |
http://<server>:8080/preview/<n>.jpg |
The current picture of page number n (counting from 0). |
http://<server>:8080/healthz |
Small JSON for health checks (Docker uses it). Answers 503 while the renderer or its browser is down. |
http://<server>:8080/api/v1/frame |
What the display fetches. |
The server runs as a normal (non-root) user and has no login. Keep port 8080 inside your home network. To use another port change the left number in ports: of docker-compose.yml, for example "9090:8080".
Updates of the server: git pull and docker compose up -d --build. Releases also publish a ready-made image, ghcr.io/robinlanger/glancebox:<version>, for amd64 and arm64.