Configuration

Environment variables

Copy .env.example to .env and edit as needed. The server reads this file on startup.

Variable	Default	Description
PORT	3001	Port the Express server listens on
NODE_ENV	development	Set to production for production builds
DOCKER_SOCKET	/var/run/docker.sock	Path to Docker socket (Docker widget)
JELLYFIN_URL	—	Base URL of your Jellyfin server, e.g. http://jellyfin:8096
JELLYFIN_API_KEY	—	Jellyfin API key (Dashboard → API Keys)
WEATHER_API_KEY	—	OpenWeatherMap API key (legacy; prefer widget config)
WEATHER_LOCATION	—	Location string, e.g. London,GB (legacy; prefer widget config)

Widget credentials vs environment variables

Most integrations now accept credentials directly in the widget config via Settings → Widgets, which stores them in the database. Environment variables remain as a fallback for Jellyfin and Weather.

Application settings

These are stored in the database (data/homepage.db) and are editable through the Settings panel.

Setting	Description
Homepage title	Browser tab title and displayed heading
Username	Displayed in the header greeting
Favicon	Custom favicon (upload via Settings → Preferences)
Clock format	12h or 24h
Temperature unit	C (Celsius) or F (Fahrenheit)
Theme	Active theme ID
Compact header	Reduces header height
Header widgets	Pin a widget (e.g. Search, Weather) to the left, centre, or right of the header
Bookmark category colour	primary, rainbow, or a fixed colour

Database

The SQLite database is created at data/homepage.db on first run. It stores:

• Widget configurations and positions
• Bookmarks and categories
• Application settings
• Themes (built-in + custom)
• Keybindings
• Backup settings

Backup & restore

Go to Settings → Backup to:

• Create a manual backup (downloads a .db file)
• Configure automatic scheduled backups
• Restore from a previous backup

In Docker, mount the data/ directory as a volume so the database persists across container restarts:

volumes:
  - ./data:/app/data