Configuration reference
Waylight reads its configuration from environment variables when it
starts. Everything that only you as the signed-in owner should decide, such
as service tiles, calendars or notification channels, lives in the web
interface instead. Settings that widen what the server may do, such as
restarting containers, are deliberately environment-only, so a stolen browser
session cannot switch them on.
Where the variables go depends on how you installed Waylight:
| Installation |
File |
Apply changes with |
| Docker Compose |
.env next to compose.yaml |
sudo docker compose up -d |
| Debian package, Raspberry Pi image |
/etc/waylight/waylight.env |
sudo systemctl restart waylight |
The fully commented .env.example
is the starting point. Only SECRET_KEY is required; the package and the Pi
image generate it on the first start.
Waylight checks the whole configuration at start-up and reports every
problem at once instead of failing on the first one.
Durations use Go syntax: 90s, 15m, 24h, 720h.
Essentials
| Variable |
Default |
Description |
SECRET_KEY |
none, required |
32 random bytes, base64 encoded (openssl rand -base64 32). Encrypts stored passwords and tokens of integrations with AES-256-GCM. Keep a copy: without it, stored credentials cannot be decrypted. |
TZ |
UTC |
Time zone for logs, calendar times without a zone and tab rules, as an IANA name such as Europe/Berlin. |
MODULES_DISABLED |
empty |
Comma-separated modules to switch off, for example docker,adguard. Module names are listed in the feature overview. |
CURRENCY_RATES |
true |
Currency conversion in the search with the ECB's daily reference rates (fetched at most once a day). false for installations without internet. See markets. |
SAMPLE_DATA |
true |
Fill a fresh installation with example tabs, widgets and data after setup. Existing data is never touched. |
CONFIG_FILE |
– |
Path to a waylight.yaml that is applied at every start. The sections it contains become read-only in the UI. See Settings as a YAML file. |
Network and access
| Variable |
Default |
Description |
BIND_ADDRESS |
0.0.0.0 |
Host address the port is published on. Docker Compose only. |
HOST_PORT |
8090 |
Host port. Docker Compose only. |
LISTEN_ADDR |
:8090 |
Address the server listens on inside the container or on the host. |
ALLOWED_CIDRS |
loopback and private ranges |
Client networks that may connect. Loopback is always allowed. Rejected and first-seen addresses are logged, which helps to tune the list. |
TRUSTED_PROXIES |
empty |
Reverse proxies whose X-Forwarded-For header is trusted. Needed behind a proxy so that the allow-list, rate limits and network tab rules see the real client address. |
PUBLIC_URL |
empty |
The public https:// address, such as https://home.example.org. Required for passkeys and for signing in to Microsoft To Do, Google Tasks and TickTick (to-do lists) and to Google Calendar and Microsoft 365 (calendar), and for password reset links by e-mail (accounts). |
COOKIE_SECURE |
false |
Set to true once the app is served over HTTPS. Adds the Secure flag and the __Host- prefix to the session cookie. |
Sign-in and sessions
| Variable |
Default |
Description |
SESSION_TTL |
720h |
How long a session stays valid without use. Each use extends it. |
SETUP_TOKEN |
random, printed to the log |
A fixed setup token of at least 16 characters, for automated installations. |
OIDC_ISSUER, OIDC_CLIENT_ID, OIDC_CLIENT_SECRET, OIDC_REDIRECT_URL |
empty |
OpenID Connect sign-in for the owner. See single sign-on. |
OIDC_ALLOWED_EMAILS, OIDC_ALLOWED_SUBJECTS |
empty |
Who may sign in through OIDC, by verified e-mail address or subject. |
OIDC_GROUPS_CLAIM |
empty |
ID token claim with a person's groups, e.g. groups. Used by single sign-on for members. |
TEAMS_BOT_APP_ID |
empty |
Licensed ee builds: the organisation's Azure Bot app ID; switches on the Teams command box search at POST /api/teams/messages, which Microsoft must reach. See Microsoft Teams. |
SLACK_APP_TOKEN |
empty |
Licensed ee builds: the app-level token (xapp-…) of the workspace's own Slack app; switches on the /home command over Socket Mode. See Slack command. |
OIDC_MEMBER_EMAILS, OIDC_MEMBER_GROUPS, OIDC_SYNC_GROUPS, OIDC_ADMIN_GROUPS |
empty |
Licensed ee builds: who becomes a member or an admin through OIDC, and which provider groups are synced. See single sign-on for members. |
SCIM_TOKEN |
empty |
Licensed ee builds: bearer token for SCIM provisioning from a directory. See directory sync. |
LDAP_URL, LDAP_BIND_DN, LDAP_BIND_PASSWORD, LDAP_BASE_DN, LDAP_USER_ATTRIBUTE, LDAP_USER_CLASS, LDAP_MEMBER_GROUPS, LDAP_SYNC_GROUPS, LDAP_ADMIN_GROUPS, LDAP_CA_FILE |
empty |
Licensed ee builds: members sign in with their LDAP or Active Directory password; LDAP_ADMIN_GROUPS makes some of them admins. See directory sync. |
AUTH_PROXY_HEADER, AUTH_PROXY_USERS |
empty |
Trust a user header set by a proxy in TRUSTED_PROXIES (forward auth). |
PASSWORD_LOGIN |
true |
Set to false to turn off the owner's password sign-in once single sign-on works. |
SSO_REQUIRE_2FA |
false |
Also ask for the local two-factor code after single sign-on. |
OIDC_BUTTON_LABEL |
empty |
The provider's name on the sign-in button, such as Microsoft ("Sign in with Microsoft"), at most 40 characters. Empty keeps "Sign in with single sign-on". |
OIDC_BUTTON_ICON |
empty |
An icon on that button: microsoft or key. |
OIDC_AUTO_REDIRECT |
false |
With PASSWORD_LOGIN=false, the sign-in page goes straight to the provider. /?local=1 still shows it. See single sign-on. |
MICROSOFT_CLIENT_ID |
built in |
Microsoft app registration for signing in with a personal Microsoft account by code, without any setup or HTTPS. Replace it with your own public client id; empty turns it off. See sign in with Microsoft. |
Actions that change other systems
All of these are off by default. Each one lists exactly what may be changed;
see the host integrations and the
security model for why.
| Variable |
Default |
Description |
DOCKER_ACTIONS |
false |
Enables restart and the log view in the Docker widget. Needs COMPOSE_PROFILES=docker-actions. |
DOCKER_ACTIONS_CONTAINERS |
empty |
Exact names of the containers that may be restarted and whose logs may be shown. |
DOCKER_ACTIONS_PROXY_URL |
http://docker-actions-proxy:2375 |
The restart-only Docker socket proxy. |
SMARTHOME_ACTIONS_ENTITIES |
empty |
Home Assistant entity IDs that may be switched or pressed, such as switch.coffee_machine. |
PROXMOX_ACTIONS_GUESTS |
empty |
Proxmox VM and container IDs that may be started and shut down, such as 100,105. |
DNS_PAUSE_PROVIDERS |
empty |
DNS filters whose blocking may be paused for 5, 30 or 60 minutes: adguard, pihole or both. Refused together with DEMO_MODE. |
Host data
| Variable |
Default |
Description |
SYSTEM_DISK_PATHS |
System=/host/rootfs in Compose |
Disks shown by the system widget, as comma-separated Label=path pairs. |
HOST_PROC |
/proc, /host/proc in Compose |
The host's procfs, read by the system module. |
HOST_SYS |
/sys, /host/sys in Compose |
The host's sysfs, for temperatures. |
DOCKER_PROXY_URL |
http://docker-socket-proxy:2375 |
The read-only Docker socket proxy. |
WIREGUARD_DIR |
/wireguard in Compose |
Directory with the export of scripts/wireguard-export.sh. |
DISKHEALTH_DIR |
/smart in Compose |
Directory with the export of scripts/smart-export.sh. |
DISKHEALTH_STALE_AFTER |
2h |
S.M.A.R.T. exports older than this are shown as unknown. |
WOL_RELAY |
host.docker.internal:9009 in Compose |
The Wake-on-LAN relay. Empty sends the broadcast directly, for installations without Docker or in the host network. |
WOL_BROADCAST |
255.255.255.255:9 |
Where the magic packet is sent, by the relay or directly. |
DEVICE_DIR |
/var/lib/waylight/device |
Raspberry Pi image only: where the chosen display mode is handed to the system service that switches the screen. |
External services
Change these only to use a mirror, your own instance or a test server.
| Variable |
Default |
Description |
TRANSIT_API_URL |
https://api.transitous.org |
MOTIS API for departures. Point it to your own MOTIS instance if you run one. |
FUEL_API_URL |
https://creativecommons.tankerkoenig.de/json |
Tankerkönig API for fuel prices. |
SPACE_LAUNCH_API_URL |
https://ll.thespacedevs.com/2.2.0/launch/upcoming/ |
Launch Library 2 for the space widget. |
SPACE_APOD_API_URL |
https://api.nasa.gov/planetary/apod |
NASA's Astronomy Picture of the Day API. |
Storage and backups
| Variable |
Default |
Description |
DATABASE_PATH |
/data/waylight.db |
The SQLite database file. |
BACKUP_DIR |
backups next to the database |
Directory for the automatic backups. |
BACKUP_INTERVAL |
24h |
How often a backup is made; at least 1h. |
BACKUP_RETENTION |
7 |
How many backups are kept. |
Operations
| Variable |
Default |
Description |
LOG_LEVEL |
info |
debug, info, warn or error. |
LOG_FORMAT |
json |
json or text. |
SHUTDOWN_TIMEOUT |
15s |
How long requests in flight may finish when the server stops. |
METRICS_ENABLED |
false |
Expose GET /metrics for Prometheus. See metrics. |
METRICS_TOKEN |
none |
Bearer token for /metrics, at least 32 characters. |
INSTALL_METHOD |
set by the image, the package and the Pi image |
docker, package or appliance. Chooses which update instructions the settings show. |
WAYLIGHT_VERSION |
latest |
The image tag Docker Compose runs. A version such as 1.2.3 pins it. Docker Compose only. |
COMPOSE_PROFILES |
empty |
Optional Compose services: wol for the Wake-on-LAN relay, docker-actions for the restart proxy. Docker Compose only. |
Look
| Variable |
Default |
Description |
DEFAULT_THEME |
amber |
Id of a built-in theme, such as amber-dark or nord, for the sign-in page and every account that has not chosen its own appearance. none keeps the plain built-in look; an unknown id logs a warning and keeps it too. See appearance. |
Sample data and demo
| Variable |
Default |
Description |
SAMPLE_WEATHER_LOCATION |
Berlin,52.52,13.41 |
Name,latitude,longitude of the example weather widget. |
SAMPLE_FEEDS |
Go Blog, Hacker News |
Example feeds, comma separated. |
DEMO_MODE |
false |
A public demo without sign-in, with sample data and canned answers instead of real integrations. See demo mode. |
DEMO_RESET_INTERVAL |
3h |
How often a demo restores its sample data. |