env.example

# Board API Configuration (required)
# Choose between Local API (faster, local network) or Cloud API (internet-based)
# 
# Mode: "local" or "cloud"
BOARD_API_MODE=local
#
# For Local API:
# - Request an enablement token at https://www.vestaboard.com/local-api
# - Use it to enable the Local API and get your API key
#   (see https://docs.vestaboard.com/docs/local-api/authentication)
# - Requires your board to be on the same network
# - Supports transition animations
# - Faster updates
BOARD_LOCAL_API_KEY=your_local_api_key_here  # Used when BOARD_API_MODE=local
BOARD_HOST=192.168.0.11  # IP or hostname (e.g., board.local)
#
# For Cloud API (alternative/fallback):
# - Get your Read/Write API key from https://web.vestaboard.com (Settings -> API)
# - Works from anywhere with internet
# - No transition support
# - If using cloud mode, set BOARD_API_MODE=cloud and use BOARD_READ_WRITE_KEY
BOARD_READ_WRITE_KEY=your_read_write_api_key_here  # Used when BOARD_API_MODE=cloud

# Board Transition Settings (optional)
# Control how the board animates when displaying new messages
# Strategy options: column (Wave), reverse-column (Drift), edges-to-center (Curtain),
#                   row, diagonal, random
# Leave empty for instant updates (no animation)
BOARD_TRANSITION_STRATEGY=
BOARD_TRANSITION_INTERVAL_MS=0  # Delay between animation steps (0 = as fast as possible)
BOARD_TRANSITION_STEP_SIZE=0     # How many columns/rows animate at once (0 = 1 at a time)

# Weather API Configuration
# Get your API key from https://www.weatherapi.com/ (recommended) or https://openweathermap.org/
WEATHER_API_KEY=your_weather_api_key_here
WEATHER_PROVIDER=weatherapi  # Options: weatherapi, openweathermap

# Location Configuration
WEATHER_LOCATION=San Francisco, CA
TIMEZONE=America/Los_Angeles

# Guest WiFi Configuration
# Enable to display WiFi credentials for guests
# Note: enable/disable via the UI or config.json (guest_wifi.enabled)
GUEST_WIFI_SSID=GuestNetwork
GUEST_WIFI_PASSWORD=YourPasswordHere
GUEST_WIFI_REFRESH_SECONDS=60

# Home Assistant Configuration
# Enable to display house status (doors, garage, etc.)
# Requires Home Assistant REST API access token
# Note: enable/disable via the UI or config.json (home_assistant.enabled)
# For local dev with docker-compose.ha.yml use: http://homeassistant:8123
HOME_ASSISTANT_BASE_URL=http://192.168.1.100:8123
HOME_ASSISTANT_ACCESS_TOKEN=your_long_lived_access_token_here
HOME_ASSISTANT_ENTITIES=[{"entity_id": "binary_sensor.front_door", "name": "Front Door"}, {"entity_id": "cover.garage_door", "name": "Garage"}]
HOME_ASSISTANT_TIMEOUT=5
HOME_ASSISTANT_REFRESH_SECONDS=30

# MQTT Configuration (Home Assistant auto-discovery and control)
# When enabled, FiestaBoard appears as a device in HA with zero config on the HA side
# Requires an MQTT broker (e.g. Mosquitto) reachable from this host
MQTT_ENABLED=false
MQTT_BROKER_HOST=localhost
MQTT_BROKER_PORT=1883
MQTT_USERNAME=
MQTT_PASSWORD=
MQTT_DISCOVERY_PREFIX=homeassistant
MQTT_BASE_TOPIC=fiestaboard
MQTT_INSTANCE_ID=fiestaboard_1
# URL shown as the "Visit" link on the FiestaBoard device page in Home Assistant.
# Set to the address your browser uses to reach FiestaBoard (e.g. http://192.168.1.50:4420
# or http://fiestaboard.local:4420). When not set, no link appears on the device page.
FIESTABOARD_EXTERNAL_URL=http://localhost:4420

# Star Trek Quotes Configuration
# Display random Star Trek quotes from TNG, Voyager, and DS9
# Note: enable/disable via the UI or config.json (star_trek_quotes.enabled)
STAR_TREK_QUOTES_RATIO=3:5:9

# Muni Transit Configuration
# Real-time SF Muni arrival predictions
# Get your free API key from https://511.org/open-data
# Note: enable/disable via the UI or config.json (muni.enabled)
MUNI_API_KEY=your_511_org_api_key_here
MUNI_REFRESH_SECONDS=60

# Traffic Configuration
# Monitor travel times to destinations with live traffic conditions
# Get your API key from Google Cloud Console (Routes API must be enabled)
# See plugins/traffic/docs/SETUP.md for detailed setup instructions
# Note: enable/disable via the UI or config.json (traffic.enabled)
GOOGLE_ROUTES_API_KEY=your_google_routes_api_key_here
TRAFFIC_REFRESH_SECONDS=300

# Bay Wheels Configuration
# Track bike availability at multiple stations
# Note: enable/disable via the UI or config.json (baywheels.enabled)
BAYWHEELS_REFRESH_SECONDS=60

# Surf Conditions Configuration
# Display surf conditions (wave height and period)
# Note: enable/disable via the UI or config.json (surf.enabled)
SURF_LATITUDE=37.7599  # Ocean Beach, SF (default)
SURF_LONGITUDE=-122.5121  # Ocean Beach, SF (default)
SURF_REFRESH_SECONDS=600  # 10 minutes

# Air Quality / Fog Configuration
# Monitor air quality and fog conditions
# Note: enable/disable via the UI or config.json (air_fog.enabled)
# PurpleAir API key (optional - for air quality data)
PURPLEAIR_API_KEY=your_purpleair_api_key_here
PURPLEAIR_SENSOR_ID=  # Optional: specific sensor ID
# OpenWeatherMap API key (optional - for visibility/fog data, separate from weather)
OPENWEATHERMAP_API_KEY=your_openweathermap_api_key_here
AIR_FOG_LATITUDE=37.7749  # San Francisco (default)
AIR_FOG_LONGITUDE=-122.4194  # San Francisco (default)
AIR_FOG_REFRESH_SECONDS=300  # 5 minutes

# Stocks Configuration
# Display US stock market prices and percentage changes
# Get a free Finnhub API key from https://finnhub.io/ (optional - enables better symbol search)
# Note: enable/disable via the UI or config.json (stocks.enabled)
FINNHUB_API_KEY=your_finnhub_api_key_here  # Optional - enables better symbol search/autocomplete
STOCKS_SYMBOLS=GOOG  # Comma-separated list of stock symbols (max 5, e.g., "GOOG,AAPL,MSFT,TSLA,NVDA")
STOCKS_TIME_WINDOW=1 Day  # Options: "1 Day", "5 Days", "1 Month", "3 Months", "6 Months", "1 Year", "2 Years", "5 Years", "ALL"
STOCKS_REFRESH_SECONDS=300  # How often to fetch stock data (default: 5 minutes)

# Silence Schedule Configuration
# Configure a time window when the board won't send updates
# Times are in your configured timezone (configured via TIMEZONE)
# The window can span midnight (e.g., 8pm to 7am)
# Note: enable/disable via the UI or config.json (silence_schedule.enabled)
SILENCE_SCHEDULE_START_TIME=20:00  # 24-hour format (8pm)
SILENCE_SCHEDULE_END_TIME=07:00  # 24-hour format (7am)

# General Configuration
# Board update interval (how often the service checks for new content)
REFRESH_INTERVAL_SECONDS=60  # Code default: 300 seconds (5 minutes) if not set; recommended: 60 seconds
# Output target: "ui" (preview only), "board" (send to board), or "both"
OUTPUT_TARGET=board

# System Configuration
# Set to "true" for production deployments
PRODUCTION=false
# Build version (automatically set during Docker builds)
VERSION=dev

# mDNS / Bonjour Configuration
# When enabled, FiestaBoard advertises itself on the local network so you
# can access it via http://fiestaboard.local:4420 (or your custom hostname).
# Requires mDNS support on the network (most home networks support this).
MDNS_HOSTNAME=fiestaboard  # Hostname without .local suffix

# =============================================================================
# Self-Update / FiestaUpdater Sidecar (5.0+)
# =============================================================================
# FiestaBoard 5.0 ships a tiny companion container, `fiestaupdater`, that can
# pull a newer image and recreate the main service from inside compose.  This
# powers the in-app "Update Now" button.
#
# To enable on a fresh install (or any existing one), set:
#     COMPOSE_PROFILES=fiestaupdater
# and run `docker compose up -d`.  The install script (scripts/install.sh)
# does this for you.  The shared bearer token is auto-generated to
# `data/.fiestaupdater-token` on first start; you can override it here.
COMPOSE_PROFILES=
FIESTAUPDATER_TOKEN=
# Internal URL of the sidecar on the compose network.  No reason to change
# unless you renamed the service.
FIESTAUPDATER_URL=http://fiestaupdater:8765

# =============================================================================
# Authentication (opt-in)
# =============================================================================
# Set to "true" to require a username + password before the FiestaBoard
# control UI / API can be used. Recommended for any FiestaBoard that is
# reachable from the public internet (e.g. hosted on a VPS).
#
# The first time the UI is opened, you'll be shown a first-run picker
# letting you either enable login or skip it. Your choice is persisted in
# data/auth.json so you don't get re-prompted on the next request.
# Setting this env var to a truthy/falsy value pins the mode and hides
# the picker. Examples:
#
#   FIESTABOARD_AUTH_ENABLED=true   # force-enable, no opt-out
#   FIESTABOARD_AUTH_ENABLED=false  # force-disable, no prompt
#   FIESTABOARD_AUTH_ENABLED=       # let the admin choose on first visit
#
# Credentials are stored in data/auth.json (passwords are scrypt-hashed,
# file mode 0600).
FIESTABOARD_AUTH_ENABLED=

# Override the session cookie lifetime in seconds (default: 7 days).
# FIESTABOARD_SESSION_TTL_SECONDS=604800

# =============================================================================
# MCP (Model Context Protocol) bearer token
# =============================================================================
# When FIESTABOARD_AUTH_ENABLED is on, external MCP clients (Claude Desktop,
# Claude Code, etc.) can't drive the cookie-based login flow. Set a token
# here and FiestaBoard's /mcp endpoint will accept it as
#     Authorization: Bearer <token>
# instead of a session cookie. A 401 from /mcp will include
#     WWW-Authenticate: Bearer realm="FiestaBoard MCP"
# so clients know to send a pre-shared token rather than attempting OAuth.
#
# Generate a value with:
#     python -c "import secrets; print(secrets.token_urlsafe(32))"
#
# Leave empty to disable token auth on /mcp (cookie auth still works).
FIESTABOARD_MCP_TOKEN=

# =============================================================================
# Secret encryption at rest
# =============================================================================
# FiestaBoard can encrypt sensitive values (API keys, board keys, plugin
# credentials) before writing them to data/config.json. The encryption key
# is loaded from FIESTABOARD_SECRET_KEY if set, otherwise a key is
# generated on first run at data/.secret_key (mode 0600).
#
# The value must be a urlsafe base64-encoded 32-byte Fernet key. Generate
# one with:
#     python -c "from cryptography.fernet import Fernet; print(Fernet.generate_key().decode())"
#
# IMPORTANT: back this key up. Losing it makes existing encrypted secrets
# unrecoverable.
FIESTABOARD_SECRET_KEY=

# Auto-restore config (timezone, install name, enabled plugins + secrets) from the
# pre-update snapshot when an upgrade boot is detected to have dropped it (#1102/#948).
# Set to 0 to disable and rely on manual /system/update/rollback instead.
FIESTABOARD_AUTO_RESTORE=1